Brightbox API Documentation 1.0.0beta

Introduction

Welcome to the Brightbox Cloud API! The API allows you to programmatically control the computing resources available to your account.

It currently allows management of the following resources:

In addition it allows management of some aspects of your User, Account and API client details.

Requirements to use the service

In order to use the Brightbox Cloud service and the API you must have a valid User profile and an Account which has been successfully verified.

New users can sign up to the service at https://manage.brightbox.com

If you were a user during the beta period of the service, you should have received instructions about how to upgrade your profile and account details to gain full access.

General concepts

Users and Accounts

In the Brightbox Cloud we differentiate between a User, a person who uses the site, and an Account which is where costs and resources are managed.

A User must agree to the terms and conditions to use the service. An Account must be setup with a valid payments card and be verified by telephone.

At the present time we are limiting each User to having one Account. This may change in the future to allow multiple users to manage one Account and a User having several Accounts.

The best way to manage your user and account details are using the management control panel at https://manage.brightbox.com

Regions and Zones

We divide our service into two geographical layers. Regions are larger areas which contain several Zones. Zones are roughly equivalent to data centres. Zones however are completely independent of each other.

The Brightbox API is currently regional. So you can interact with several Zones through the API.

Resource IDs

All resources have a unique and immutable ID. These consist of a three letter code, a dash and approximately five alphanumeric characters. The characters are actually a number encoded as Base36 to save on typing. As such the number range may expand and become longer.

API tools and client libraries

Whilst the Brightbox Cloud API is already pretty simple to use we already provide a number of tools to help. Some of these may help you rather than having to work against the API directly.

Brightbox CLI

We provide a set of command line tools to access and manage most of the resources. Details are available at the documentation site.

The CLI tools are available as either a Ruby gem or a Ubuntu/Debian package.

Fog (Ruby Library)

Fog is a cloud abstraction library for Ruby that standardise some of the details of different cloud providers APIs.

Support for the Cloud API in Fog is officially maintained by Brightbox.

Our CLI tools use Fog.

Apache Libcloud (Python Library)

Libcloud is a standard Python library that abstracts away differences among multiple cloud provider APIs. We added support for our API to libcloud, which is now included upstream.

http://libcloud.apache.org/

Chef/Knife plugin

rubiojr kindly wrote a Knife plugin to allow you to use Chef to provision Brightbox cloud servers in one line.

Blog post covering: Bootstrapping an Ubuntu Image in Brightbox’s Cloud using knife

API concepts

API endpoint URLs

All communication with the API is required to be secured using SSL so the protocol must always be HTTPS.

The API endpoint URL for the GB1 region is: api.gb1.brightbox.com

API versioning

The Brightbox Cloud API uses semantic versioning

The current version of the API is 1.0.0beta but the URL only includes the major and minor parts of the version number

To use a particular version of the API, add it to the base API endpoint URL e.g api.gb1.brightbox.com/1.0/

DateTime and Timezone

All Times are stored and reported in UTC. The ISO8601 format (e.g. 2011-09-13T16:09:54Z) is used throughout the API. The DateTimes are returned as strings since JSON does not have a DateTime object in the specification.

Authentication

Authentication is based on the “Autonomous client” workflow, as described in OAuth2.0 version 10. (http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-1.4.4).

Before you can access the Brightbox API an API Client must first be created for the Account via the Brightbox Control Panel. This API client is used to access protected resources by requesting an access token to pass in with requests.

An API client is limited to only access resources connected to the owning Account so multiple clients must be used to manage multiple accounts.

Requesting an access token

To request an access token the Client must send a POST request to https://api.gb1.brightbox.com/token

The request must use Basic HTTP authentication using the client_id as username and client_secret as password.

In the unlikely event that basic authentication is not a part of the client or library you are using, you can prepare the header yourself. Join the client_id, a colon (”:”) and the client_secret together (e.g. cli-entid:dld4kl3kln53k) and base64 encode (RFC2617) the string (e.g. Y2xpLWVudGlkOmRsZDRrbDNrbG41M2s=). Include the Authorization header with the value Basic Y2xpLWVudGlkOmRsZDRrbDNrbG41M2s=.

An access token request must include two parameters passed as a JSON object in the body of the request. First is the client_id and the second is a grant type of “none”. You will need to ensure the Content-Type is set to application/json.

ParameterDescription
client_idThe identifier of the API client. e.g “cli-entid”
grant_type“none”
Example JSON request:
POST /token HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: Basic Y2xpLWVudGlkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

{"client_id": "cli-entid", "grant_type": "none"}

A successful request returns a JSON response including the access_token. Access tokens expire after 7200 seconds. Client applications should be designed to handle re-authentication on receipt of a 401 Unauthorised response from the API.

Unsuccessful requests return a 401 Unauthorised response if the credentials are wrong. For any other mistakes such as the wrong grant type it will return a 400 Bad Request.

Example JSON response:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
 "access_token":"k1bjflpsaj8wnrbrwzad0eqo36nxiha",
 "expires_in": 7200
}

See http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-4.2

Making API requests

Requests are made by including the access token in the HTTP Authorization header with the “OAuth” scheme. The token attribute must be set to the value returned from the token request.

The token is passed with any requests to the main API endpoint (api.gb1.brightbox.com) in the following form:

GET /1.0/servers HTTP/1.1
Host: api.gb1.brightbox.com
Authorization: OAuth k1bjflpsaj8wnrbrwzad0eqo36nxiha

See http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5.1.1

If the token is valid for the requested resource the response body is return. If the token is invalid or expired the response will be a 401 Unauthorised HTTP response with details of the error.

 HTTP/1.1 401 Unauthorized
 WWW-Authenticate: OAuth error='token_expired'

See http://tools.ietf.org/html/draft-ietf-oauth-v2-10#section-5.2

Request format

To make a request of the API the Content-Type of the request must be in JSON. See http://www.json.org/

The format of is that of a JSON object with a name for each attribute or link a resource has.

The JSON specification does not require an Object’s names and values to be ordered. Unrecognised parameters being sent will be ignored.

Representation format

The responses you receive from the API will be represented in JSON.

Each resource can be represented in one of three ways.

RepresentationDescription
FullThis is a full view of the resource. All of the attributes are included and linked resources appear in the output as well
NestedThis is a shorter representation that is used when this resource is beneath another full resource. A nested resource is secondary data to the main resource being accessed
CollectedThis is used when the resource is a member of a collection. It is shorter than the full response since many may be returned in one go

The format of is that of a JSON object with a name for each attribute or link a resource has.

Only the first level of a linked resource is shown as well as a url to access that resource.

The type of representation that is returned by an API action is detailed in the summary of each action.

Exact details of the response contents are included in the resource’s documentation.

The JSON specification does not require an Object’s names and values to be ordered. You should not expect the responses to return in a particular order since that is not guaranteed.

Examples of each type of representation are given near the resource’s main documentation

Full representation

Full representations show as much information about a resource as is possible. This includes all attributes for the resource. It also includes the nested representations for any other resources that are linked to the requested resource.

This allows you to see a summary of related resources without too many additional API requests.

Nested representation

Nested representations are shorter summaries of a resource intended to appear beneath a main resource.

A nested resource is named using the relationship between the two resources.

When a resource is collected to a number of other resources, this collection is represented using the nested representations rather than a collection representation.

Collected representation

Collected representations are used when the resource is a member of a collection. Some details are omitted since several sets of results are expected to be returned and including full details would create very large responses.

A collection representation is wrapped in an Array in the returned JSON response. This allows iteration across the collection.

Data type formats

Data typeFormatExampleDescription
AccountIDacc-3nsa9A Unique Identifier
ClientIDcli-dhjk2A Unique Identifier
CloudipIDcip-2sjo9A Unique Identifier
ImageIDimg-fj23sA Unique Identifier
ServerIDsrv-42ftsdA Unique Identifier
ServerTypeIDtyp-f89d09A Unique Identifier
UserIDusr-kl8d08A Unique Identifier
ZoneIDzon-dk92jsA Unique Identifier
DateTimeISO86012010-07-23T11:39:14ZThis is a date and time represented as a string
CountryCodeISO 3166-1 two letter codeGBISO County code
CountryNameISO 3166-1 official nameUnited KingdomCountry name
EmailRFC2822hello@brightbox.co.ukA valid email address
VATNumberGB916139623A Valid EU VAT number
Telephone+448456585545A Valid International telephone number in E.164 format prefixed with ’+’
Architecturei686,x86_64i686OS architecture (32-bit or 64-bit)
HealthcheckJavascript Object{"type": "http", "port": 80, "request": "/", "interval": 5000, "timeout": 5000, "threshold_up": 3, "threshold_down": 3}Valid Healthcheck Object. Required attributes: “type”, “port”. All other attributes default to the values in the example
ListenerJavascript Object{"protocol": "http", "in": 80, "out": 8080, "timeout:50000"}Valid Listener object. Timeout is optional and specified in miliseconds (default 50000). Valid protocols include ‘tcp’, ‘http’ and ‘http+ws’. The protocol ‘http+ws’ allows both http and websocket connections. Websocket connections have a timeout of one day, if a timeout is specified for ‘http+ws’ it will only apply to standard http connections.
Port TranslatorJavascript Object{"protocol": "tcp", "incoming": 80, "outgoing": 8080}Valid Port translator object. Valid protocols include ‘tcp’, ‘udp’.
Node parameterJavascript Object{"node": "srv-3a97e"}Node declaration passing an identifier as the node attribute. Node is required.
PasswordString of at least 8 characters+Tw9f&h3aPThe password should be between 8 and 72 characters long.
BalancerPolicyround-robinThe balancing policies available for a Load Balancer. This can currently be least-connections or round-robin.

Metadata service

The Brightbox cloud provides an EC2 compatible metadata service so that Servers are able to retrieve information about themselves while booting and whilst running. It is accessed via HTTP from the cloud server and uses IP-based authentication.

$ curl http://169.254.169.254/latest/meta-data
hostname
instance-id
instance-type
local-hostname
local-ipv4
placement/
public-ipv4
public-keys/

For example, to be able to retrieve the SSH public keys and add them to the authorized_keys file. The public SSH key associated with the User’s profile is available via this metadata service.

$ curl http://169.254.169.254/latest/meta-data/public-keys/usr-kl34r/openssh-key

This is already setup on the Official Brightbox Ubuntu images so you only need to worry about this if you are using your own image.

Custom metadata can be also be attached to a Server using the user_data attribute during creation. This data is treated as opaque and is stored and returned as application/octet-stream.

See the AWS Developer Guide for details.

Resources

Account

Brightbox services are provided through an Account. A typical customer will have at least one Account through which they buy their Servers and other services. They may create multiple accounts if they wish e.g to manage servers for separate clients of theirs.

Accounts have limits on the resources that they can use. These are currently:

Viewing current usage is possible via the Account show action or via the management control panel.

States

State Description
pending Account has been created but signup process is incomplete
active Account is active
overdue Account has overdue invoices
warning Account suspension is pending due to outstanding payments
suspended Account and services are suspended due to outstanding payments, billable account activity is prevented pending payment
terminated Account has been terminated due to terms and conditions violations e.g. non-payment
closed Account has been closed by the customer
deleted Account has been deleted from the system

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string AccountID acc-3jd8s true true Unique Identifier
url string URL true true URL to access details of resource
name string String Brightbox Systems Ltd. true true
status string String active true true
address_1 string String Leeds Media Centre false false First line of address
address_2 string String 21 Savile Mount false false Second line of address
city string String Leeds false false
county string String false false
postcode string String LS7 3HZ false false Postcode or Zipcode
country_code string CountryCode GB false false County code
country_name string CountryName United Kingdom false false Country name
vat_registration_number string,null VATNumber GB916139623 false false Valid EU VAT number (http://tinyurl.com/2fp4c2e)
telephone_number string Telephone +448456585545 false false Contact telephone number to speak to someone authorised to manage the account
telephone_verified true,false Boolean true false false Has the contact number been verified? If not Account may not be used to make certain requests
verified_telephone string,null E164 Telephone +448456585545 false false The actual number used to successfully verify the account
verified_at string,null DateTime true false false Has the contact number been verified? If not Account may not be used to make certain requests
verified_ip string,null IP Address true false false Has the contact number been verified? If not Account may not be used to make certain requests
valid_credit_card boolean Boolean true false false Has the Account's payment card been checked as valid?
created_at string DateTime 2011-11-11T11:11:11Z false false The date and time when the Account was created
ram_limit number Integer 20480 false true The total RAM usage this Account is limited to in MB
ram_used number Integer 2048 false true The total RAM used by this Account in MB
dbs_ram_limit number Integer 8192 false true The total RAM this account can use for database servers in MB
dbs_ram_used number Integer 8192 false true The total RAM this account is using for database servers in MB
cloud_ips_limit number Integer 5 false true The total number of Cloud IP addresses this Account is limited to
cloud_ips_used number Integer 5 false true The total number of Cloud IP addresses used by this Account
load_balancers_limit number Integer 5 false true The total number of Load Balancers this Account is limited to
load_balancers_used number Integer 5 false true The total number of Load Balancers used by this Account
library_ftp_host string String ftp.library.gb1.brightbox.com false false FTP host for uploading images to the cloud image library
library_ftp_user string String acc-3jd8sh false false FTP user for uploading images to the cloud image library (same as account ID)
library_ftp_password string,null String d25yd0dRArKSDQNS false false FTP password for uploading images to the cloud image library (can be regenerated using the reset_ftp_password action)

Representations

Full Account representation example
{"id": "acc-43ks4",
 "resource_type": "account",
 "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
 "name": "Brightbox",
 "status": "active",
 "address_1": "Leeds Media Centre",
 "address_2": "21 Savile Mount",
 "city": "Leeds",
 "county": "",
 "postcode": "LS7 3HZ",
 "country_code": "GB",
 "country_name": "United Kingdom",
 "vat_registration_number": "GB916139623",
 "telephone_number": "+448456585545",
 "telephone_verified": true,
 "verified_telephone": "+448456585545",
 "verified_at": 2011-10-01 00:01:00 UTC,
 "verified_ip": "81.82.12.11",
 "created_at": 2011-10-01 00:00:00 UTC,
 "ram_limit": 32768,
 "ram_used": 2048,
 "cloud_ips_limit": 10,
 "cloud_ips_used": 1,
 "load_balancers_limit": 5,
 "load_balancers_used": 1,
 "dbs_ram_limit": 8192,
 "dbs_ram_used": 0,
 "valid_credit_card": true,
 "library_ftp_host": "ftp.library.gb1.brightbox.com",
 "library_ftp_user": "acc-43ks4",
 "library_ftp_password": null,
 "clients":
  [{"id": "cli-dsse2",
    "resource_type": "api_client",
    "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
    "name": "dev client",
    "description": "Development client from laptop",
    "revoked_at": null}],
 "images":
  [],
 "servers":
  [],
 "load_balancers":
  [{"id": "lba-1235f",
    "resource_type": "load_balancer",
    "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
    "name": "",
    "status": "creating",
    "created_at": 2011-10-01 01:00:00 UTC,
    "deleted_at": null}],
 "database_servers":
  [],
 "database_snapshots":
  [],
 "cloud_ips":
  [{"id": "cip-k4a25",
    "resource_type": "cloud_ip",
    "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
    "status": "mapped",
    "public_ip": "109.107.50.0",
    "reverse_dns": null,
    "name": "product website ip"}],
 "server_groups":
  [{"id": "grp-sda44",
    "resource_type": "server_group",
    "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
    "name": "default",
    "description": null,
    "created_at": 2011-10-01 00:00:00 UTC,
    "default": true}],
 "firewall_policies":
  [{"id": "fwp-j3654",
    "resource_type": "firewall_policy",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
    "default": true,
    "name": "default",
    "created_at": 2011-10-01 00:00:00 UTC,
    "description": null}],
 "owner":
  {"id": "usr-kl435",
   "resource_type": "user",
   "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
   "name": "John Jarvis",
   "email_address": "jjarvis@example.com"},
 "users":
  [{"id": "usr-kl435",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
    "name": "John Jarvis",
    "email_address": "jjarvis@example.com"}],
 "zones":
  [{"id": "zon-328ds",
    "resource_type": "zone",
    "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
    "handle": "gb1"}]}
Collection Account representation example
[{"id": "acc-43ks4",
  "resource_type": "account",
  "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
  "name": "Brightbox",
  "status": "active",
  "ram_limit": 32768,
  "ram_used": 2048,
  "dbs_ram_limit": 8192,
  "dbs_ram_used": 0,
  "cloud_ips_limit": 10,
  "cloud_ips_used": 1,
  "load_balancers_limit": 5,
  "load_balancers_used": 1,
  "clients":
   [{"id": "cli-dsse2",
     "resource_type": "api_client",
     "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
     "name": "dev client",
     "description": "Development client from laptop",
     "revoked_at": null}],
  "images":
   [],
  "servers":
   [],
  "load_balancers":
   [{"id": "lba-1235f",
     "resource_type": "load_balancer",
     "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
     "name": "",
     "status": "creating",
     "created_at": 2011-10-01 01:00:00 UTC,
     "deleted_at": null}],
  "database_servers":
   [],
  "database_snapshots":
   [],
  "cloud_ips":
   [{"id": "cip-k4a25",
     "resource_type": "cloud_ip",
     "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
     "status": "mapped",
     "public_ip": "109.107.50.0",
     "reverse_dns": null,
     "name": "product website ip"}],
  "server_groups":
   [{"id": "grp-sda44",
     "resource_type": "server_group",
     "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
     "name": "default",
     "description": null,
     "created_at": 2011-10-01 00:00:00 UTC,
     "default": true}],
  "firewall_policies":
   [{"id": "fwp-j3654",
     "resource_type": "firewall_policy",
     "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
     "default": true,
     "name": "default",
     "created_at": 2011-10-01 00:00:00 UTC,
     "description": null}],
  "owner":
   {"id": "usr-kl435",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
    "name": "John Jarvis",
    "email_address": "jjarvis@example.com"},
  "users":
   [{"id": "usr-kl435",
     "resource_type": "user",
     "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
     "name": "John Jarvis",
     "email_address": "jjarvis@example.com"}],
  "zones":
   [{"id": "zon-328ds",
     "resource_type": "zone",
     "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
     "handle": "gb1"}]}]
Nested Account representation example
{"id": "acc-43ks4",
 "resource_type": "account",
 "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
 "name": "Brightbox",
 "status": "active"}

Actions

List request
HTTP MethodURLReturnsNormal response
GET/1.0/accountsCollection200 OK
Parameters

This action does not have any parameters.

Get request

Get full details of the account.

HTTP MethodURLReturnsNormal response
GET/1.0/accounts/(account_id)Member200 OK
Parameters

This action does not have any parameters.

Update request

Update some details of the account.

HTTP MethodURLReturnsNormal response
PUT/1.0/accounts/(account_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String Brightbox Systems Ltd.
address_1 String First line of address Leeds Media Centre
address_2 String Second line of address 21 Savile Mount
city String Leeds
county String
postcode String Postcode or Zipcode LS7 3HZ
country_code CountryCode GB
vat_registration_number VATNumber Must be a valid EU VAT number GB916139623
telephone_number Telephone Contact telephone number to speak to someone authorised to manage the account +448456585545
Reset ftp password request

Reset the image library ftp password for the account.

The response is the only time the new password is available in plaintext.

HTTP MethodURLReturnsNormal response
POST/1.0/accounts/(account_id)/reset_ftp_passwordMember200 OK
Parameters

This action does not have any parameters.

Api client

An application registered to an account in order to authenticate via OAuth2.0

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string ApiClient cli-e690d true true A unique identifier used to identify the client in requests
url string URL true true URL to access details of resource
name string String Reboot script true true Human readable name
secret string,null String 79fdsjhkhk3 false false An shared secret the client must present when authenticating
description string String CLI script to reboot servers programmatically true true Verbose description of this client

Representations

Full Api client representation example
{"id": "cli-dsse2",
 "resource_type": "api_client",
 "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
 "name": "dev client",
 "description": "Development client from laptop",
 "secret": null,
 "revoked_at": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"}}
Collection Api client representation example
[{"id": "cli-dsse2",
  "resource_type": "api_client",
  "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
  "name": "dev client",
  "description": "Development client from laptop",
  "revoked_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"}}]
Nested Api client representation example
{"id": "cli-dsse2",
 "resource_type": "api_client",
 "url": "https://api.gb1.brightbox.com/1.0/api_clients/cli-dsse2",
 "name": "dev client",
 "description": "Development client from laptop",
 "revoked_at": null}

Actions

List request

Lists summary details of API clients owned by the account.

HTTP MethodURLReturnsNormal response
GET/1.0/api_clientsCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request

Create a new API client for the account.

HTTP MethodURLReturnsNormal response
POST/1.0/api_clientsMember201 Created
Parameters
Required Name Type Default Description Example
name String Reboot script
description String CLI script to reboot servers programmatically
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get full details of the API client.

HTTP MethodURLReturnsNormal response
GET/1.0/api_clients/(api_client_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of the API client.

HTTP MethodURLReturnsNormal response
PUT/1.0/api_clients/(api_client_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String Reboot script
description String CLI script to reboot servers programmatically
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Destroy the API client.

HTTP MethodURLReturnsNormal response
DELETE/1.0/api_clients/(api_client_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Reset secret request

Resets the secret used by the API client to a new generated value.

The response is the only time the new secret is available in plaintext.

Already authenticated tokens will still continue to be valid until expiry.

HTTP MethodURLReturnsNormal response
POST/1.0/api_clients/(api_client_id)/reset_secretMember200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Cloud ip

A IPv4 publicly routed IP address that can be dynamically remapped.

States

State Description
unmapped The CloudIP is not in use and available for mapping
mapped CloudIP is currently in use

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string CloudipID cip-ja8ub true true Unique identifier
url string URL true true URL to access details of resource
public_ip string IPAddress 109.107.42.129 true true IPv4 address
status string String mapped true true Current state of the Cloud IP
reverse_dns string Hostname cip-109-107-42-129.gb1.brightbox.com true true The reverse DNS entry for the CloudIP
name string Name product website ip true true Name assigned to the cloud IP
port_translators array Array [{"incoming": 80, "outgoing": 8080, "protocol": "http"}, {"incoming": 81, "outgoing": 581, "protocol": "udp"] false true Array of port translators

Representations

Full Cloud ip representation example
{"id": "cip-k4a25",
 "resource_type": "cloud_ip",
 "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
 "status": "mapped",
 "public_ip": "109.107.50.0",
 "reverse_dns": null,
 "port_translators":
  [{"protocol": "http",
    "incoming": 443,
    "outgoing": 2443}],
 "name": "product website ip",
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "interface":
  {"id": "int-ds42k",
   "resource_type": "interface",
   "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
   "mac_address": "02:24:19:00:00:ee",
   "ipv4_address": "81.15.16.17"},
 "server":
  {"id": "srv-lv426",
   "resource_type": "server",
   "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
   "name": "",
   "status": "active",
   "hostname": "srv-lv426",
   "fqdn": "srv-lv426.gb1.brightbox.com",
   "created_at": 2011-10-01 01:00:00 UTC,
   "started_at": 2011-10-01 01:01:00 UTC,
   "deleted_at": null},
 "load_balancer": null,
 "server_group": null,
 "database_server": null}
Collection Cloud ip representation example
[{"id": "cip-k4a25",
  "resource_type": "cloud_ip",
  "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
  "status": "mapped",
  "public_ip": "109.107.50.0",
  "reverse_dns": null,
  "port_translators":
   [{"protocol": "http",
     "incoming": 443,
     "outgoing": 2443}],
  "name": "product website ip",
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "interface":
   {"id": "int-ds42k",
    "resource_type": "interface",
    "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
    "mac_address": "02:24:19:00:00:ee",
    "ipv4_address": "81.15.16.17"},
  "server":
   {"id": "srv-lv426",
    "resource_type": "server",
    "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
    "name": "",
    "status": "active",
    "hostname": "srv-lv426",
    "fqdn": "srv-lv426.gb1.brightbox.com",
    "created_at": 2011-10-01 01:00:00 UTC,
    "started_at": 2011-10-01 01:01:00 UTC,
    "deleted_at": null},
  "load_balancer": null,
  "server_group": null,
  "database_server": null}]
Nested Cloud ip representation example
{"id": "cip-k4a25",
 "resource_type": "cloud_ip",
 "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
 "status": "mapped",
 "public_ip": "109.107.50.0",
 "reverse_dns": null,
 "name": "product website ip"}

Actions

List request

Lists summary details of cloud IP addresses owned by the account.

HTTP MethodURLReturnsNormal response
GET/1.0/cloud_ipsCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request

Requests a new cloud IP address for the account.

HTTP MethodURLReturnsNormal response
POST/1.0/cloud_ipsMember201 Created
Parameters
Required Name Type Default Description Example
reverse_dns Hostname Reverse DNS hostname cip-109-107-42-129.gb1.brightbox.com
name String Name for Cloud IP product website ip
port_translators Array Port on which external clients connect and port on which your service is listening. {"protocol": "tcp", "incoming": 443, "outgoing": 2443}
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get full details of the cloud IP address.

HTTP MethodURLReturnsNormal response
GET/1.0/cloud_ips/(cloud_ip_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of the cloud IP address.

HTTP MethodURLReturnsNormal response
PUT/1.0/cloud_ips/(cloud_ip_id)Member200 OK
Parameters
Required Name Type Default Description Example
reverse_dns Hostname Reverse DNS hostname cip-109-107-42-129.gb1.brightbox.com
name String Name for Cloud IP product website ip
port_translators Array Port on which external clients connect and port on which your service is listening. {"protocol": "tcp", "incoming": 443, "outgoing": 2443}
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Release the cloud IP address from the account’s ownership.

HTTP MethodURLReturnsNormal response
DELETE/1.0/cloud_ips/(cloud_ip_id)No body200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Map request

Maps (or points) a cloud IP address at a server’s interface or a load balancer to allow them to respond to public requests.

HTTP MethodURLReturnsNormal response
POST/1.0/cloud_ips/(cloud_ip_id)/mapNo body202 Accepted
Parameters
Required Name Type Default Description Example
Yes destination InterfaceID|LoadBalancerID The ID of an Interface or LoadBalancer to map the Cloud IP against int-abcde
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Unmap request

Unmaps a cloud IP address from its current destination making it available to remap. This remains in the account’s pool of addresses.

HTTP MethodURLReturnsNormal response
POST/1.0/cloud_ips/(cloud_ip_id)/unmapNo body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Collaboration

A collaboration forms the link between an Account and a User, giving the User access to the specified Account. As a collaboration is created, the User is invited to accept the collaboration via email. The collaboration can be accepted or rejected via the User Collaboration’s accept or reject methods. Once the collaboration is complete either party can end the collaboration. Account administrators can call delete on the Collaboration or the User can call delete on the User Collaboration.

States

State Description
pending Collaboration was created and is awaiting acceptence/rejection from the User (via User Collaboration)
accepted Collaboration was accepted and is active
rejected Collaboration was rejected by the user
cancelled Collaboration was deleted before it entered the accepted state
ended Collaboration was accepted but has since been ended by either party

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string CollaborationID col-klek3 true true Unique ID for the collaboration
url string URL true true URL to access details of resource
email string Email user@example.net true true
role string String admin true true Simple and stable name of role
role_label string String Account administrator true true Verbose name of role
status string String false true Current state of the collaboration
created_at string Datetime 2013-04-23T10:40:14Z true true Time of Collaboration creation (UTC)
started_at string Datetime 2013-05-23T10:40:14Z true true Time of Collaboration start (UTC)
finished_at string Datetime 2013-06-23T10:40:14Z true true Time of Collaboration finish (UTC)

Representations

Full Collaboration representation example
{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": null,
 "email": "tclock@example.com",
 "role": "admin",
 "created_at": 2013-03-24 00:00:00 UTC,
 "started_at": 2013-04-10 00:00:00 UTC,
 "finished_at": 2013-05-10 00:00:00 UTC,
 "role_label": "Collaborator",
 "user": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "inviter":
  {"id": "usr-kl435",
   "resource_type": "user",
   "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
   "name": "John Jarvis",
   "email_address": "jjarvis@example.com"}}
Collection Collaboration representation example
[{"id": null,
  "resource_type": "collaboration",
  "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
  "status": null,
  "email": "tclock@example.com",
  "role": "admin",
  "created_at": 2013-03-24 00:00:00 UTC,
  "started_at": 2013-04-10 00:00:00 UTC,
  "finished_at": 2013-05-10 00:00:00 UTC,
  "role_label": "Collaborator",
  "user": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "inviter":
   {"id": "usr-kl435",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
    "name": "John Jarvis",
    "email_address": "jjarvis@example.com"}}]
Nested Collaboration representation example
{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": null,
 "email": "tclock@example.com",
 "role": "admin",
 "created_at": 2013-03-24 00:00:00 UTC,
 "started_at": 2013-04-10 00:00:00 UTC,
 "finished_at": 2013-05-10 00:00:00 UTC,
 "role_label": "Collaborator"}

Actions

Create request

Invites the given email address to collaborate with the specified account. Existing users will be able to accept the collaboration whilst those without a Brightbox account will be invited to create one.

HTTP MethodURLReturnsNormal response
POST/1.0/collaborationsMember201 Created
Parameters
Required Name Type Default Description Example
Yes email String john@example.com Email address of user to invite john@example.com
Yes role String admin Role to grant to the user. Currently only `admin` admin
Allowed Account states

This action can only be performed when the owning Account is in the following states:

List request

Lists all the collaborations for the given account

HTTP MethodURLReturnsNormal response
GET/1.0/collaborationsCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Shows details of the collaboration

HTTP MethodURLReturnsNormal response
GET/1.0/collaborations/(collaboration_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Resend request

Resends the invitation email to the collaborator

HTTP MethodURLReturnsNormal response
POST/1.0/collaborations/(collaboration_id)/resendNo body200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Cancels or completes the collaboration

HTTP MethodURLReturnsNormal response
DELETE/1.0/collaborations/(collaboration_id)No body200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Database server

States

State Description
creating The DatabaseServer is being created
active The DatabaseServer is available for use
deleting The DatabaseServer is being deleted and is not available for use
deleted The DatabaseServer has been deleted and is not available for use
failing The DatabaseServer is being failed and is not available for use
failed The DatabaseServer has been failed and is not available for use

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string String dbs-12345 true true Unique Identifier
url string URL true true URL to access details of resource
name string String My web server true true Editable user label
description string String Main user DB true true Editable user label
status string String active true true
database_engine string String mysql true true The DBMS engine of the Database Server
database_version string String 5.5 true true The version of the given engine in use
admin_username string,null String admin false false Initial username required to login
admin_password string,null String k43;2kd432f false false Initial password required to login
created_at string Datetime 2010-07-23T10:40:14Z true true Time of resource creation (UTC)
updated_at string Datetime 2010-07-23T10:40:14Z true true Time of resource creation (UTC)
deleted_at string Datetime 2010-07-23T10:43:14Z true true Time of resource creation (UTC)
allow_access array Array ['srv-12345', '192.168.1.1'] true true An array of resources allowed to access the database. Accepted values include `any`, `IPv4 address`, `server identifier`, `server group identifier`.

Representations

Full Database server representation example
{"id": "dbs-123ab",
 "resource_type": "database_server",
 "url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
 "name": "My Database Server",
 "description": "Application one's DBS",
 "admin_username": "admin",
 "admin_password": "k43;2kd432f",
 "allow_access":
  [],
 "database_engine": "mysql",
 "database_version": "5.5",
 "status": "active",
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "database_server_type":
  {"id": "dbt-12345",
   "resource_type": "database_type",
   "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
   "name": "Small",
   "description": "Database Type Small",
   "disk_size": 81920,
   "ram": 2048},
 "cloud_ips":
  [],
 "zone":
  {"id": "zon-328ds",
   "resource_type": "zone",
   "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
   "handle": "gb1"}}
Collection Database server representation example
[{"id": "dbs-123ab",
  "resource_type": "database_server",
  "url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
  "name": "My Database Server",
  "description": "Application one's DBS",
  "allow_access":
   [],
  "database_engine": "mysql",
  "database_version": "5.5",
  "status": "active",
  "created_at": "2011-10-01T01:00:00Z",
  "updated_at": "2011-11-01T01:00:00Z",
  "deleted_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "database_server_type":
   {"id": "dbt-12345",
    "resource_type": "database_type",
    "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
    "name": "Small",
    "description": "Database Type Small",
    "disk_size": 81920,
    "ram": 2048},
  "cloud_ips":
   [],
  "zone":
   {"id": "zon-328ds",
    "resource_type": "zone",
    "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
    "handle": "gb1"}}]
Nested Database server representation example
{"id": "dbs-123ab",
 "resource_type": "database_server",
 "url": "https://api.gb1.brightbox.com/1.0/database_servers/dbs-123ab",
 "name": "My Database Server",
 "description": "Application one's DBS",
 "allow_access":
  [],
 "database_engine": "mysql",
 "database_version": "5.5",
 "status": "active",
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null}

Actions

List request
HTTP MethodURLReturnsNormal response
GET/1.0/database_serversCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request
HTTP MethodURLReturnsNormal response
POST/1.0/database_serversMember202 Accepted
Parameters
Required Name Type Default Description Example
name String My web server
description String Main user DB
engine String mysql Database engine to request mysql
version String 5.5 Database version to request 5.5
allow_access Array ["192.168.1.2", "192.168.1.1"] ... ["192.168.1.2", "192.168.1.1"]
snapshot String dbi-12345 dbi-12345
zone String zon-12345 zon-12345
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request
HTTP MethodURLReturnsNormal response
GET/1.0/database_servers/(database_server_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request
HTTP MethodURLReturnsNormal response
PUT/1.0/database_servers/(database_server_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String My web server
description String Main user DB
allow_access Array ["192.168.1.2", "192.168.1.1"] ... ["192.168.1.2", "192.168.1.1"]
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request
HTTP MethodURLReturnsNormal response
DELETE/1.0/database_servers/(database_server_id)No body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Snapshot request
HTTP MethodURLReturnsNormal response
POST/1.0/database_servers/(database_server_id)/snapshotNo body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Reset password request
HTTP MethodURLReturnsNormal response
POST/1.0/database_servers/(database_server_id)/reset_passwordNo body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Database snapshot

States

State Description
creating The snapshot is being taken and prepared for reuse
available The snapshot is available for use
deleted The snapshot details have been deleted
failed The snapshot failed to complete successfully

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string String dbi-12345 true true Unique Identifier
url string URL true true URL to access details of resource
name string String My web server true true Editable user label
description string String Main user DB true true Editable user label
status string String active true true
database_engine string String mysql true true The engine of the database used to create this snapshot
database_version string String 5.5 true true The version of the database engine used to create this snapshot
size number Integer 10485760 true true Size of database partition in megabytes
created_at string Datetime 2010-07-23T10:40:14Z true true Time of resource creation (UTC)
updated_at string Datetime 2010-07-23T10:40:14Z true true Time of resource creation (UTC)
deleted_at string Datetime 2010-07-23T10:43:14Z true true Time of resource creation (UTC)

Representations

Full Database snapshot representation example
{"id": "dbi-12345",
 "resource_type": "database_snapshot",
 "url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
 "name": "Snapshot of dbs-123ab 12 Feb 13:18",
 "description": "",
 "status": "available",
 "database_engine": "mysql",
 "database_version": "5.5",
 "source": null,
 "size": 0,
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"}}
Collection Database snapshot representation example
[{"id": "dbi-12345",
  "resource_type": "database_snapshot",
  "url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
  "name": "Snapshot of dbs-123ab 12 Feb 13:18",
  "description": "",
  "status": "available",
  "database_engine": "mysql",
  "database_version": "5.5",
  "source": null,
  "size": 0,
  "created_at": "2011-10-01T01:00:00Z",
  "updated_at": "2011-11-01T01:00:00Z",
  "deleted_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"}}]
Nested Database snapshot representation example
{"id": "dbi-12345",
 "resource_type": "database_snapshot",
 "url": "https://api.gb1.brightbox.com/1.0/database_snapshots/dbi-12345",
 "name": "Snapshot of dbs-123ab 12 Feb 13:18",
 "description": "",
 "status": "available",
 "database_engine": "mysql",
 "database_version": "5.5",
 "source": null,
 "size": 0,
 "created_at": "2011-10-01T01:00:00Z",
 "updated_at": "2011-11-01T01:00:00Z",
 "deleted_at": null}

Actions

List request
HTTP MethodURLReturnsNormal response
GET/1.0/database_snapshotsCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request
HTTP MethodURLReturnsNormal response
GET/1.0/database_snapshots/(database_snapshot_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of the server.

HTTP MethodURLReturnsNormal response
PUT/1.0/database_snapshots/(database_snapshot_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String Editable label My web server
description String Editable label Main user DB
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request
HTTP MethodURLReturnsNormal response
DELETE/1.0/database_snapshots/(database_snapshot_id)No body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Database type

All Database Servers are created with a type. The type represents the available RAM and Disk space of the Server.

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string String dbt-abcde true true Unique Identifier
url string URL true true URL to access details of resource
name string String Database Nano true true The name of this Database Server type
description string String Database Nano Server true true The description of this Database Server type
ram number Integer 2048 true true RAM in megabytes
disk_size number Integer 81920 true true Disk size in megabytes

Representations

Full Database type representation example
{"id": "dbt-12345",
 "resource_type": "database_type",
 "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
 "name": "Small",
 "description": "Database Type Small",
 "disk_size": 81920,
 "ram": 2048}
Collection Database type representation example
[{"id": "dbt-12345",
  "resource_type": "database_type",
  "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
  "name": "Small",
  "description": "Database Type Small",
  "disk_size": 81920,
  "ram": 2048}]
Nested Database type representation example
{"id": "dbt-12345",
 "resource_type": "database_type",
 "url": "https://api.gb1.brightbox.com/1.0/database_types/dbt-12345",
 "name": "Small",
 "description": "Database Type Small",
 "disk_size": 81920,
 "ram": 2048}

Actions

List request

List database server types.

HTTP MethodURLReturnsNormal response
GET/1.0/database_typesCollection200 OK
Parameters

This action does not have any parameters.

Get request

Get details of the database server type.

HTTP MethodURLReturnsNormal response
GET/1.0/database_types/(database_type_id)Member200 OK
Parameters

This action does not have any parameters.

Firewall policy

A collection of Firewall Rules

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string FirewallPolicyID fwp-r4532 true true Unique identifier
url string URL true true URL to access details of resource
default true,false Boolean false false Is this the default for the account
name string,null String the_wall false false An optional name of the policy
description string,null String false false An optional description of the policy
created_at string Datetime 2010-07-23T10:40:14Z true true Time of Firewall Policy creation (UTC)

Representations

Full Firewall policy representation example
{"id": "fwp-j3654",
 "resource_type": "firewall_policy",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
 "default": true,
 "name": "default",
 "created_at": 2011-10-01 00:00:00 UTC,
 "description": null,
 "server_group":
  {"id": "grp-sda44",
   "resource_type": "server_group",
   "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
   "name": "default",
   "description": null,
   "created_at": 2011-10-01 00:00:00 UTC,
   "default": true},
 "rules":
  [{"id": "fwr-k32ls",
    "resource_type": "firewall_rule",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
    "source": "srv-lv426",
    "source_port": "80,443,21",
    "destination": null,
    "destination_port": null,
    "protocol": "tcp",
    "icmp_type_name": null,
    "description": null,
    "created_at": 2011-10-01 00:00:00 UTC}]}
Collection Firewall policy representation example
[{"id": "fwp-j3654",
  "resource_type": "firewall_policy",
  "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
  "default": true,
  "name": "default",
  "created_at": 2011-10-01 00:00:00 UTC,
  "description": null,
  "server_group":
   {"id": "grp-sda44",
    "resource_type": "server_group",
    "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
    "name": "default",
    "description": null,
    "created_at": 2011-10-01 00:00:00 UTC,
    "default": true},
  "rules":
   [{"id": "fwr-k32ls",
     "resource_type": "firewall_rule",
     "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
     "source": "srv-lv426",
     "source_port": "80,443,21",
     "destination": null,
     "destination_port": null,
     "protocol": "tcp",
     "icmp_type_name": null,
     "description": null,
     "created_at": 2011-10-01 00:00:00 UTC}]}]
Nested Firewall policy representation example
{"id": "fwp-j3654",
 "resource_type": "firewall_policy",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
 "default": true,
 "name": "default",
 "created_at": 2011-10-01 00:00:00 UTC,
 "description": null}

Actions

List request

Lists summary details of firewall policies

HTTP MethodURLReturnsNormal response
GET/1.0/firewall_policiesCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request

Create a new firewall policy for the account.

Optionally applying to a server group at creation time.

HTTP MethodURLReturnsNormal response
POST/1.0/firewall_policiesMember201 Created
Parameters
Required Name Type Default Description Example
server_group ServerGroupID
name String Editable label the_wall
description String Longer editable description
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get details of the firewall policy

HTTP MethodURLReturnsNormal response
GET/1.0/firewall_policies/(firewall_policy_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Updates details of the firewall policy

HTTP MethodURLReturnsNormal response
PUT/1.0/firewall_policies/(firewall_policy_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String Editable label the_wall
description String Longer editable description
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Apply to request

Applies firewall policy to given server group

HTTP MethodURLReturnsNormal response
POST/1.0/firewall_policies/(firewall_policy_id)/apply_toMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes server_group ServerGroupID Server Group to apply to
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Remove request

Removes firewall policy from given server group

HTTP MethodURLReturnsNormal response
POST/1.0/firewall_policies/(firewall_policy_id)/removeMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes server_group ServerGroupID Server Group to remove
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Destroy the firewall policy if not in use.

HTTP MethodURLReturnsNormal response
DELETE/1.0/firewall_policies/(firewall_policy_id)No body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Firewall rule

A firewall rule representing a single ‘ACCEPT’ rule

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string FirewallRuleID fwr-83208 true true Unique identifier
url string URL true true URL to access details of resource
source string String false false Subnet, ServerGroup or ServerID. 'any','10.1.1.23/32' or 'srv-4ktk4'
source_port string String false false single port, multiple ports or range separated by '-' or ':'; upto 255 characters example - '80', '80,443,21' or '3000-3999'
destination string String false false Subnet, ServerGroup or ServerID. '10.1.1.23/32' or 'srv-4ktk4'
destination_port string String false false single port, multiple ports or range separated by '-' or ':'; upto 255 characters example '80', '80,443,21' or '3000-3999'
protocol string String tcp false false Protocol Number or One of 'tcp', 'udp', 'icmp'
icmp_type_name string String echo-request false false ICMP type name. 'echo-request', 'echo-reply'
description string,null String false false Arbitary string
created_at string Datetime 2010-07-23T10:40:14Z true true Time of Firewall Rule creation (UTC)

Representations

Full Firewall rule representation example
{"id": "fwr-k32ls",
 "resource_type": "firewall_rule",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
 "source": "srv-lv426",
 "source_port": "80,443,21",
 "destination": null,
 "destination_port": null,
 "icmp_type_name": null,
 "protocol": "tcp",
 "description": null,
 "created_at": 2011-10-01 00:00:00 UTC,
 "firewall_policy":
  {"id": "fwp-j3654",
   "resource_type": "firewall_policy",
   "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
   "default": true,
   "name": "default",
   "created_at": 2011-10-01 00:00:00 UTC,
   "description": null}}
Collection Firewall rule representation example
[{"id": "fwr-k32ls",
  "resource_type": "firewall_rule",
  "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
  "source": "srv-lv426",
  "source_port": "80,443,21",
  "destination": null,
  "destination_port": null,
  "protocol": "tcp",
  "icmp_type_name": null,
  "description": null,
  "created_at": 2011-10-01 00:00:00 UTC,
  "firewall_policy":
   {"id": "fwp-j3654",
    "resource_type": "firewall_policy",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
    "default": true,
    "name": "default",
    "created_at": 2011-10-01 00:00:00 UTC,
    "description": null}}]
Nested Firewall rule representation example
{"id": "fwr-k32ls",
 "resource_type": "firewall_rule",
 "url": "https://api.gb1.brightbox.com/1.0/firewall_rules/fwr-k32ls",
 "source": "srv-lv426",
 "source_port": "80,443,21",
 "destination": null,
 "destination_port": null,
 "protocol": "tcp",
 "icmp_type_name": null,
 "description": null,
 "created_at": 2011-10-01 00:00:00 UTC}

Actions

Create request

Create a new firewall rule for a firewall policy.

HTTP MethodURLReturnsNormal response
POST/1.0/firewall_rulesMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes firewall_policy FirewallPolicyID
protocol String tcp
source String Required unless destination is set.
source_port String
destination String Required unless source is set
destination_port String
icmp_type_name String echo-request
description String
Get request

Get full details of the firewall rule.

HTTP MethodURLReturnsNormal response
GET/1.0/firewall_rules/(firewall_rule_id)Member200 OK
Parameters

This action does not have any parameters.

Update request

Update some settings of the firewall rule.

HTTP MethodURLReturnsNormal response
PUT/1.0/firewall_rules/(firewall_rule_id)Member202 Accepted
Parameters
Required Name Type Default Description Example
protocol String tcp
source String Required unless destination is set.
source_port String
destination String Required unless source is set
destination_port String
icmp_type_name String echo-request
description String
Delete request

Destroy the firewall rule.

HTTP MethodURLReturnsNormal response
DELETE/1.0/firewall_rules/(firewall_rule_id)No body202 Accepted
Parameters

This action does not have any parameters.

Image

An Image is virtual disk image used as the basis of the server.

States

State Description
creating This Image is being created from a Server and is not yet complete
available This Image is available for selection
deprecated This Image is not listed but is available for new servers
unavailable This Image is no longer available for new servers
deleting This Image is being deleted and is no longer available for use
deleted This image has been deleted and is no longer available for use
failed This image failed to create and is unavailable for use

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string ImageID img-9vxqi true true Unique Identifier
url string URL true true URL to access details of resource
name string String Brightbox Lucid 32 true true Editable label for this image
username string String ubuntu true true Username to use - when logging in to server booted with the image
status string String available true true One of the suitable states for the Image to be in
description string String Jeremy's debian ec2 image true true A description of the Image
source string String jeremy_debian-32_ec2 true true The source of this image (i.e the uploaded file or the server it was a snapshot of)
source_type string String upload true true The type of source for this image (i.e upload or snapshot)
arch string Architecture x86_64 true true OS architecture
created_at string Datetime true true The time this image was created/registered (UTC)
public true,false Boolean true true true Is this Image available to other customers?
official true,false Boolean true true true Is this Image an official Brightbox provided one
compatibility_mode true,false Boolean true false true Does this image require a non-virtio VM shell?
virtual_size number Integer 1024 false true The virtual size of the disk image "container" in MB
disk_size number Integer 395 false true The actual size of the data within this Image in MB
min_ram number,null Integer 1024 false true The minimum amount of RAM needed for this Image in MB. If unspecified is null
owner string AccountID acc-bright true true The account ID who created this account
licence_name string String Windows 2008 Server false false The Licence name of this image

Representations

Full Image representation example
{"id": "img-3ikco",
 "resource_type": "image",
 "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
 "name": "Ubuntu Lucid 10.04 server",
 "status": "available",
 "username": "ubuntu",
 "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
 "source": "ubuntu-lucid-daily-i64-server-20110509",
 "arch": "x86_64",
 "created_at": 2011-05-09 12:00:00 UTC,
 "official": true,
 "public": true,
 "compatibility_mode": false,
 "source_type": "upload",
 "disk_size": 560,
 "virtual_size": 1409,
 "min_ram": null,
 "owner": "acc-43ks4",
 "licence_name": "Windows 2008",
 "ancestor": null}
Collection Image representation example
[{"id": "img-3ikco",
  "resource_type": "image",
  "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
  "name": "Ubuntu Lucid 10.04 server",
  "username": "ubuntu",
  "status": "available",
  "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
  "source": "ubuntu-lucid-daily-i64-server-20110509",
  "arch": "x86_64",
  "created_at": 2011-05-09 12:00:00 UTC,
  "owner": "acc-43ks4",
  "official": true,
  "public": true,
  "compatibility_mode": false,
  "source_type": "upload",
  "disk_size": 560,
  "virtual_size": 1409,
  "min_ram": null,
  "ancestor": null}]
Nested Image representation example
{"id": "img-3ikco",
 "resource_type": "image",
 "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
 "name": "Ubuntu Lucid 10.04 server",
 "username": "ubuntu",
 "status": "available",
 "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
 "source": "ubuntu-lucid-daily-i64-server-20110509",
 "arch": "x86_64",
 "created_at": 2011-05-09 12:00:00 UTC,
 "official": true,
 "public": true,
 "owner": "acc-43ks4"}

Actions

List request

Lists summary details of images available for use by the Account. It includes those available to all customers

HTTP MethodURLReturnsNormal response
GET/1.0/imagesCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request

Create a new image for the account by registering it against an image stored within the Brightbox cloud image library.

The disk image must be in place before you can attempt to create a reference in the API.

HTTP MethodURLReturnsNormal response
POST/1.0/imagesMember201 Created
Parameters
Required Name Type Default Description Example
Yes source String Filename of the image file uploaded to /incoming via FTP jeremy_debian-32_ec2
Yes arch Architecture OS architecture this image is built for x86_64
name String Name for this image. If no name is specified, a name will be autogenerated based on the source filename & current time. Can be modified later. Brightbox Lucid 32
username String Username for the image ubuntu
public Boolean true
compatibility_mode Boolean true
description String Jeremy's debian ec2 image
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get full details of the image.

HTTP MethodURLReturnsNormal response
GET/1.0/images/(image_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of the image.

HTTP MethodURLReturnsNormal response
PUT/1.0/images/(image_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String Brightbox Lucid 32
username String
arch String x86_64
status String available
public Boolean true
compatibility_mode Boolean true
description String Jeremy's debian ec2 image
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Destroy the image.

HTTP MethodURLReturnsNormal response
DELETE/1.0/images/(image_id)No body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Interface

An Interface resource represents the network interface of a Server. Each Server has one Interface, created automatically when the Server is created. An interface has an IPv4 (“local”) address and, optionally, an IPv6 (“public”) address.

Future versions of the API should support creation of multiple Interfaces per Server to enable, for example, multiple SSL applications per server.

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string InterfaceID int-mc3a9 true true Unique Identifier
url string URL true true URL to access details of resource
mac_address string MAC Address 02:24:19:6e:18:36 true true The MAC address for this Interface
ipv4_address string IP Address 10.110.24.54 true true The IPv4 address for this Interface
ipv6_address string IPv6 Address 2a02:1348:dead:0:0024:19ff:fe6e:1835 true true The IPv6 address for this Interface

Representations

Full Interface representation example
{"id": "int-ds42k",
 "resource_type": "interface",
 "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
 "mac_address": "02:24:19:00:00:ee",
 "ipv4_address": "81.15.16.17",
 "server":
  {"id": "srv-lv426",
   "resource_type": "server",
   "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
   "name": "",
   "status": "active",
   "hostname": "srv-lv426",
   "fqdn": "srv-lv426.gb1.brightbox.com",
   "created_at": 2011-10-01 01:00:00 UTC,
   "started_at": 2011-10-01 01:01:00 UTC,
   "deleted_at": null}}
Collection Interface representation example
[{"id": "int-ds42k",
  "resource_type": "interface",
  "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
  "mac_address": "02:24:19:00:00:ee",
  "ipv4_address": "81.15.16.17",
  "server":
   {"id": "srv-lv426",
    "resource_type": "server",
    "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
    "name": "",
    "status": "active",
    "hostname": "srv-lv426",
    "fqdn": "srv-lv426.gb1.brightbox.com",
    "created_at": 2011-10-01 01:00:00 UTC,
    "started_at": 2011-10-01 01:01:00 UTC,
    "deleted_at": null}}]
Nested Interface representation example
{"id": "int-ds42k",
 "resource_type": "interface",
 "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
 "mac_address": "02:24:19:00:00:ee",
 "ipv4_address": "81.15.16.17"}

Actions

Get request

Get full details of the interface.

HTTP MethodURLReturnsNormal response
GET/1.0/interfaces/(interface_id)Member200 OK
Parameters

This action does not have any parameters.

Load balancer

A load balancer balances requests between multiple servers

States

State Description
creating The LoadBalancer is being created
active The LoadBalancer is available for use
deleting The LoadBalancer is being deleted and is not available for use
deleted The LoadBalancer has been deleted and is not available for use
failing The LoadBalancer is being failed and is not available for use
failed The LoadBalancer has been failed and is not available for use

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string LoadBalancerID lba-dja0s true true Unique identifier
url string URL true true URL to access details of resource
name string String My first loadbalancer true true Editable user label
status string String active true true See states
listeners array Array [{"in": 80, "out": 8080, "protocol": "http", "timeout": 50000}, {"in": 81, "out": 81, "protocol": "http+ws", "timeout": 10000}] false true Array of Listener objects
policy string BalancerPolicy least-connections false false Method of load balancing (either least-connections or round-robin)
healthcheck object Healthcheck {"type": "http", "request": "/", "port": 80, "interval": 5000, "timeout": 5000, "threshold_up": 3, "threshold_down": 3} false false Healthcheck options
created_at string DateTime true true Time of LoadBalancer creation (UTC)
deleted_at string DateTime true true Time of LoadBalancer deletion (UTC)

Representations

Full Load balancer representation example
{"id": "lba-1235f",
 "resource_type": "load_balancer",
 "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
 "name": "",
 "policy": "least-connections",
 "status": "creating",
 "created_at": 2011-10-01 01:00:00 UTC,
 "deleted_at": null,
 "listeners":
  [{"protocol": "http",
    "in": 80,
    "out": 80,
    "timeout": 50000}],
 "healthcheck":
  {"type": "http",
   "request": "/",
   "port": 80,
   "interval": 5000,
   "timeout": 5000,
   "threshold_up": 3,
   "threshold_down": 3},
 "certificate": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "cloud_ips":
  [],
 "nodes":
  [{"id": "srv-lv426",
    "resource_type": "server",
    "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
    "name": "",
    "status": "active",
    "hostname": "srv-lv426",
    "fqdn": "srv-lv426.gb1.brightbox.com",
    "created_at": 2011-10-01 01:00:00 UTC,
    "started_at": 2011-10-01 01:01:00 UTC,
    "deleted_at": null}]}
Collection Load balancer representation example
[{"id": "lba-1235f",
  "resource_type": "load_balancer",
  "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
  "name": "",
  "status": "creating",
  "listeners":
   [{"protocol": "http",
     "in": 80,
     "out": 80,
     "timeout": 50000}],
  "created_at": 2011-10-01 01:00:00 UTC,
  "deleted_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "cloud_ips":
   [],
  "nodes":
   [{"id": "srv-lv426",
     "resource_type": "server",
     "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
     "name": "",
     "status": "active",
     "hostname": "srv-lv426",
     "fqdn": "srv-lv426.gb1.brightbox.com",
     "created_at": 2011-10-01 01:00:00 UTC,
     "started_at": 2011-10-01 01:01:00 UTC,
     "deleted_at": null}]}]
Nested Load balancer representation example
{"id": "lba-1235f",
 "resource_type": "load_balancer",
 "url": "https://api.gb1.brightbox.com/1.0/load_balancers/lba-1235f",
 "name": "",
 "status": "creating",
 "created_at": 2011-10-01 01:00:00 UTC,
 "deleted_at": null}

Actions

List request

Lists summary details of load balancers owned by the account.

HTTP MethodURLReturnsNormal response
GET/1.0/load_balancersCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request

Create a new load balancer for the account.

HTTP MethodURLReturnsNormal response
POST/1.0/load_balancersMember202 Accepted
Parameters
Required Name Type Default Description Example
name String Editable label My first loadbalancer
Yes nodes Array Array of Node parameters [{"node": "srv-abcde"}]
policy String least-connections Method of Load balancing to use least-connections
certificate_pem String A X509 SSL certificate in PEM format. Must be included along with 'certificate_key'. If intermediate certificates are required they should be concatenated after the main certificate
certificate_key String The RSA private key used to sign the certificate in PEM format. Must be included along with 'certificate_pem'
Yes listeners Array What port to listen on, port to pass through to and protocol (tcp, http or http+ws) of listener. Timeout is optional and specified in milliseconds (default is 50000). {"protocol": "http", "in": 80, "out": 80, "timeout": 50000}
Yes healthcheck Healthcheck Healthcheck options - only "port" and "type" required {"type": "http", "port": 80}
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get full details of the load balancer.

HTTP MethodURLReturnsNormal response
GET/1.0/load_balancers/(load_balancer_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of the load balancer.

HTTP MethodURLReturnsNormal response
PUT/1.0/load_balancers/(load_balancer_id)Member202 Accepted
Parameters
Required Name Type Default Description Example
name String Editable label My first loadbalancer
nodes Array Array of Node parameters [{"node": "srv-abcde"}]
policy String least-connections Method of Load balancing to use least-connections
certificate_pem String A X509 SSL certificate in PEM format. Must be included along with 'certificate_key'. If intermediate certificates are required they should be concatenated after the main certificate
certificate_key String The RSA private key used to sign the certificate in PEM format. Must be included along with 'certificate_pem'
listeners Array What port to listen on, port to pass through to and protocol (tcp, http or http+ws) of listener. Timeout is optional and specified in milliseconds (default is 50000). {"protocol": "http", "in": 80, "out": 80, "timeout": 50000}
healthcheck Healthcheck Healthcheck options - only "port" and "type" required {"type": "http", "port": 80}
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Add nodes request

Add a number of nodes to the load balancer

HTTP MethodURLReturnsNormal response
POST/1.0/load_balancers/(load_balancer_id)/add_nodesMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes nodes Array Array of Node parameters [{"node": "srv-abcde"}]
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Remove nodes request

Remove a number of nodes from the load balancer

HTTP MethodURLReturnsNormal response
POST/1.0/load_balancers/(load_balancer_id)/remove_nodesMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes nodes Array Array of Node parameters [{"node": "srv-abcde"}]
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Add listeners request

Adds a number of listeners to the load balancer to enable balancing across nodes for those settings.

HTTP MethodURLReturnsNormal response
POST/1.0/load_balancers/(load_balancer_id)/add_listenersMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes listeners Array Array of Listener parameters. Timeout is optional and specified in milliseconds. {"protocol": "http", "in": 80, "out": 80, "timeout": 10000}
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Remove listeners request

Removes a number of listeners from a load balancer to cease balancing across nodes for those settings.

HTTP MethodURLReturnsNormal response
POST/1.0/load_balancers/(load_balancer_id)/remove_listenersMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes listeners Array Array of Listener parameters {"protocol": "http", "in": 80, "out": 80}
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Destroy the LoadBalancer

HTTP MethodURLReturnsNormal response
DELETE/1.0/load_balancers/(load_balancer_id)No body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Server

A Server is a single cloud virtual machine running an operating system defined by the Image used to create it. There are several specifications of servers (Server Types) available.

The only required argument (at this time) is the Image you would like to use for the server. All other values will use a default value.

States

State Description
creating Server is being prepared for use
active Server is available
inactive Server is shutdown
deleting Server is currently being deleted
deleted Server has been decommissioned
failed Server has failed and is no longer available
unavailable Server is currently unavailable

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string ServerID srv-3a97e true true Unique Identifier
url string URL true true URL to access details of resource
name string String My web server true true Editable user label
status string active true true See states
hostname string String srv-3a97e true true hostname
fqdn string String srv-3a97e.gb1.brightbox.com true true Full qualified domain name
created_at string Datetime 2010-07-23T10:40:14Z true true Time of server creation (UTC)
deleted_at string,null Datetime 2010-07-23T10:41:00Z true true Time server was deleted
started_at string,null Datetime 2010-07-23T10:45:16Z true true Time server was last started
user_data string,null Base64 false false User definable data for use by the metadata service (must be Base64 encoded before submitting to API)
compatibility_mode true,false Boolean true false true Does this server require a non-virtio VM shell?
console_url string,null String false false If active, URL that console page is available
console_token string,null String jlk4klj2 false false One-time session password for console page on. Null unless part of an activate_console call
console_token_expires string,null Datetime 2010-07-23T10:45:16Z false false Time that latest active console session is valid until

Representations

Full Server representation example
{"id": "srv-lv426",
 "resource_type": "server",
 "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
 "name": "",
 "status": "active",
 "hostname": "srv-lv426",
 "created_at": 2011-10-01 01:00:00 UTC,
 "started_at": 2011-10-01 01:01:00 UTC,
 "deleted_at": null,
 "user_data": null,
 "fqdn": "srv-lv426.gb1.brightbox.com",
 "compatibility_mode": false,
 "console_url": null,
 "console_token": null,
 "console_token_expires": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "image":
  {"id": "img-3ikco",
   "resource_type": "image",
   "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
   "name": "Ubuntu Lucid 10.04 server",
   "username": "ubuntu",
   "status": "available",
   "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
   "source": "ubuntu-lucid-daily-i64-server-20110509",
   "arch": "x86_64",
   "created_at": 2011-05-09 12:00:00 UTC,
   "official": true,
   "public": true,
   "owner": "acc-43ks4"},
 "server_type":
  {"id": "typ-zx45f",
   "resource_type": "server_type",
   "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
   "name": "Small",
   "status": "available",
   "cores": 2,
   "ram": 2048,
   "disk_size": 81920,
   "handle": "small"},
 "zone":
  {"id": "zon-328ds",
   "resource_type": "zone",
   "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
   "handle": "gb1"},
 "cloud_ips":
  [{"id": "cip-k4a25",
    "resource_type": "cloud_ip",
    "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
    "status": "mapped",
    "public_ip": "109.107.50.0",
    "reverse_dns": null,
    "name": "product website ip"}],
 "interfaces":
  [{"id": "int-ds42k",
    "resource_type": "interface",
    "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
    "mac_address": "02:24:19:00:00:ee",
    "ipv4_address": "81.15.16.17"}],
 "snapshots":
  [],
 "server_groups":
  [{"id": "grp-sda44",
    "resource_type": "server_group",
    "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
    "name": "default",
    "description": null,
    "created_at": 2011-10-01 00:00:00 UTC,
    "default": true}]}
Collection Server representation example
[{"id": "srv-lv426",
  "resource_type": "server",
  "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
  "name": "",
  "status": "active",
  "hostname": "srv-lv426",
  "fqdn": "srv-lv426.gb1.brightbox.com",
  "compatibility_mode": false,
  "created_at": 2011-10-01 01:00:00 UTC,
  "started_at": 2011-10-01 01:01:00 UTC,
  "deleted_at": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "image":
   {"id": "img-3ikco",
    "resource_type": "image",
    "url": "https://api.gb1.brightbox.com/1.0/images/img-3ikco",
    "name": "Ubuntu Lucid 10.04 server",
    "username": "ubuntu",
    "status": "available",
    "description": "Expands root partition automatically. login: ubuntu using stored ssh key",
    "source": "ubuntu-lucid-daily-i64-server-20110509",
    "arch": "x86_64",
    "created_at": 2011-05-09 12:00:00 UTC,
    "official": true,
    "public": true,
    "owner": "acc-43ks4"},
  "server_type":
   {"id": "typ-zx45f",
    "resource_type": "server_type",
    "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
    "name": "Small",
    "status": "available",
    "cores": 2,
    "ram": 2048,
    "disk_size": 81920,
    "handle": "small"},
  "zone":
   {"id": "zon-328ds",
    "resource_type": "zone",
    "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
    "handle": "gb1"},
  "cloud_ips":
   [{"id": "cip-k4a25",
     "resource_type": "cloud_ip",
     "url": "https://api.gb1.brightbox.com/1.0/cloud_ips/cip-k4a25",
     "status": "mapped",
     "public_ip": "109.107.50.0",
     "reverse_dns": null,
     "name": "product website ip"}],
  "interfaces":
   [{"id": "int-ds42k",
     "resource_type": "interface",
     "url": "https://api.gb1.brightbox.com/1.0/interfaces/int-ds42k",
     "mac_address": "02:24:19:00:00:ee",
     "ipv4_address": "81.15.16.17"}],
  "snapshots":
   [],
  "server_groups":
   [{"id": "grp-sda44",
     "resource_type": "server_group",
     "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
     "name": "default",
     "description": null,
     "created_at": 2011-10-01 00:00:00 UTC,
     "default": true}]}]
Nested Server representation example
{"id": "srv-lv426",
 "resource_type": "server",
 "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
 "name": "",
 "status": "active",
 "hostname": "srv-lv426",
 "fqdn": "srv-lv426.gb1.brightbox.com",
 "created_at": 2011-10-01 01:00:00 UTC,
 "started_at": 2011-10-01 01:01:00 UTC,
 "deleted_at": null}

Actions

List request

Lists summary details of servers owned by the account.

HTTP MethodURLReturnsNormal response
GET/1.0/serversCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request

Create a new server for the account based on the required disk image.

Optionally can setup the type of server, zone to locate it, groups to join and custom metadata.

HTTP MethodURLReturnsNormal response
POST/1.0/serversMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes image ImageID
name String Editable label My web server
server_type ServerTypeID
zone ZoneID Zone in which to create new Server
user_data Base64
server_groups Array Array of server groups to add server to ["grp-abcde"]
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get full details of the server.

HTTP MethodURLReturnsNormal response
GET/1.0/servers/(server_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of the server.

HTTP MethodURLReturnsNormal response
PUT/1.0/servers/(server_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String Editable label My web server
user_data Base64 User defined metadata
compatibility_mode Boolean Server needs to be shutdown and restarted for changes to this to take effect true
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Destroy the server and free up the resources.

HTTP MethodURLReturnsNormal response
DELETE/1.0/servers/(server_id)No body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Start request

Will issue a start request for the server to become active.

HTTP MethodURLReturnsNormal response
POST/1.0/servers/(server_id)/startNo body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Stop request

Will issue a stop request for the server to become inactive.

HTTP MethodURLReturnsNormal response
POST/1.0/servers/(server_id)/stopNo body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Shutdown request

Will issue a safe shutdown request for the server.

HTTP MethodURLReturnsNormal response
POST/1.0/servers/(server_id)/shutdownNo body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Activate console request

Enable console access via VNC to the server for 15 minutes.

HTTP MethodURLReturnsNormal response
POST/1.0/servers/(server_id)/activate_consoleMember202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Snapshot request

Will issue a request to snapshot the Server

HTTP MethodURLReturnsNormal response
POST/1.0/servers/(server_id)/snapshotNo body202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Server group

A grouping of Servers

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string ServerGroupID grp-kl43d true true Unique identifier
url string URL true true URL to access details of resource
name string String Web servers true true Editable user label
created_at string Datetime 2010-07-23T10:40:14Z true true Time of Server Group creation (UTC)
description string String Web servers for the main website app true true Editable user description
default true,false Boolean false false Is this the default for the account

Representations

Full Server group representation example
{"id": "grp-sda44",
 "resource_type": "server_group",
 "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
 "name": "default",
 "description": null,
 "created_at": 2011-10-01 00:00:00 UTC,
 "default": true,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "firewall_policy":
  {"id": "fwp-j3654",
   "resource_type": "firewall_policy",
   "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
   "default": true,
   "name": "default",
   "created_at": 2011-10-01 00:00:00 UTC,
   "description": null},
 "servers":
  [{"id": "srv-lv426",
    "resource_type": "server",
    "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
    "name": "",
    "status": "active",
    "hostname": "srv-lv426",
    "fqdn": "srv-lv426.gb1.brightbox.com",
    "created_at": 2011-10-01 01:00:00 UTC,
    "started_at": 2011-10-01 01:01:00 UTC,
    "deleted_at": null}]}
Collection Server group representation example
[{"id": "grp-sda44",
  "resource_type": "server_group",
  "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
  "name": "default",
  "description": null,
  "created_at": 2011-10-01 00:00:00 UTC,
  "default": true,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "firewall_policy":
   {"id": "fwp-j3654",
    "resource_type": "firewall_policy",
    "url": "https://api.gb1.brightbox.com/1.0/firewall_policies/fwp-j3654",
    "default": true,
    "name": "default",
    "created_at": 2011-10-01 00:00:00 UTC,
    "description": null},
  "servers":
   [{"id": "srv-lv426",
     "resource_type": "server",
     "url": "https://api.gb1.brightbox.com/1.0/servers/srv-lv426",
     "name": "",
     "status": "active",
     "hostname": "srv-lv426",
     "fqdn": "srv-lv426.gb1.brightbox.com",
     "created_at": 2011-10-01 01:00:00 UTC,
     "started_at": 2011-10-01 01:01:00 UTC,
     "deleted_at": null}]}]
Nested Server group representation example
{"id": "grp-sda44",
 "resource_type": "server_group",
 "url": "https://api.gb1.brightbox.com/1.0/server_groups/grp-sda44",
 "name": "default",
 "description": null,
 "created_at": 2011-10-01 00:00:00 UTC,
 "default": true}

Actions

List request

Lists summary details of server groups owned by the account.

HTTP MethodURLReturnsNormal response
GET/1.0/server_groupsCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Create request

Create a new server group for the account.

HTTP MethodURLReturnsNormal response
POST/1.0/server_groupsMember202 Accepted
Parameters
Required Name Type Default Description Example
name String Editable user label Web servers
description String Editable user description Web servers for the main website app
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get details of the server group.

HTTP MethodURLReturnsNormal response
GET/1.0/server_groups/(server_group_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of the server group.

HTTP MethodURLReturnsNormal response
PUT/1.0/server_groups/(server_group_id)Member202 Accepted
Parameters
Required Name Type Default Description Example
name String Editable user label Web servers
description String Editable user description Web servers for the main website app
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Add servers request

Add a number of servers to the server group.

HTTP MethodURLReturnsNormal response
POST/1.0/server_groups/(server_group_id)/add_serversMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes servers Array Array of Server parameters to add [{"server": "srv-abcd"}, {"server": "srv-12345"}]
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Remove servers request

Remove a number of servers from the server group.

HTTP MethodURLReturnsNormal response
POST/1.0/server_groups/(server_group_id)/remove_serversMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes servers Array Array of Server parameters to remove [{"server": "srv-abcd"}, {"server": "srv-12345"}]
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Move servers request

Removes a number of server from the server group and adds them to another server group given in parameters.

HTTP MethodURLReturnsNormal response
POST/1.0/server_groups/(server_group_id)/move_serversMember202 Accepted
Parameters
Required Name Type Default Description Example
Yes servers Array Array of Server parameters to move [{"server": "srv-abcd"}, {"server": "srv-12345"}]
Yes destination server_group ServerGroup to move servers to grp-abcde
Allowed Account states

This action can only be performed when the owning Account is in the following states:

Delete request

Destroy the server group if not in use.

HTTP MethodURLReturnsNormal response
DELETE/1.0/server_groups/(server_group_id)Member202 Accepted
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Server type

ServerType represents what we might currently call a product. All servers are created with a server type, which describes it’s configuration.

States

State Description
experimental This server type is not yet available
available This server type is available for selection
deprecated This configuration is no longer available for new servers

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string ServerTypeID typ-a97e6 true true Unique Identifier
url string URL true true URL to access details of resource
handle string,null String nano true true Unique (but editable) handle for this ServerType
name string String Brightbox Nano true true The name of this ServerType
status string String true true The state of the ServerType
cores number Integer 2 true true Number of CPU cores
ram number Integer 2048 true true RAM in megabytes
disk_size number Integer true true Disk size in megabytes

Representations

Full Server type representation example
{"id": "typ-zx45f",
 "resource_type": "server_type",
 "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
 "name": "Small",
 "status": "available",
 "cores": 2,
 "ram": 2048,
 "disk_size": 81920,
 "handle": "small"}
Collection Server type representation example
[{"id": "typ-zx45f",
  "resource_type": "server_type",
  "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
  "name": "Small",
  "status": "available",
  "cores": 2,
  "ram": 2048,
  "disk_size": 81920,
  "handle": "small"}]
Nested Server type representation example
{"id": "typ-zx45f",
 "resource_type": "server_type",
 "url": "https://api.gb1.brightbox.com/1.0/server_types/typ-zx45f",
 "name": "Small",
 "status": "available",
 "cores": 2,
 "ram": 2048,
 "disk_size": 81920,
 "handle": "small"}

Actions

List request

Lists summary details of server types available to the account.

HTTP MethodURLReturnsNormal response
GET/1.0/server_typesCollection200 OK
Parameters

This action does not have any parameters.

Get request

Get full details of the server type.

HTTP MethodURLReturnsNormal response
GET/1.0/server_types/(server_type_id)Member200 OK
Parameters

This action does not have any parameters.

User

Customers interact with Brightbox by creating a User (also known as “registering”) on the Brightbox system and then logging in using their credentials (email,password). A user may have access to many Accounts, whether as the Owner or with limited permissions.

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string UserID usr-e690d true true Unique ID for user
url string URL true true URL to access details of resource
name string String true true
email_address string Email user@example.net true true
email_verified true,false Boolean false true
ssh_key string,null String false false This User's SSH public key (is available to meta-data service to enable scripted configuration)
messaging_pref true,false Boolean false false Receive marketing communications

Representations

Full User representation example
{"id": "usr-kl435",
 "resource_type": "user",
 "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
 "name": "John Jarvis",
 "email_address": "jjarvis@example.com",
 "email_verified": true,
 "ssh_key": "",
 "messaging_pref": true,
 "default_account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "accounts":
  [{"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"}]}
Collection User representation example
[{"id": "usr-kl435",
  "resource_type": "user",
  "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
  "name": "John Jarvis",
  "email_address": "jjarvis@example.com",
  "email_verified": true,
  "default_account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "accounts":
   [{"id": "acc-43ks4",
     "resource_type": "account",
     "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
     "name": "Brightbox",
     "status": "active"}]}]
Nested User representation example
{"id": "usr-kl435",
 "resource_type": "user",
 "url": "https://api.gb1.brightbox.com/1.0/users/usr-kl435",
 "name": "John Jarvis",
 "email_address": "jjarvis@example.com"}

Actions

List request

Lists summary details of user.

HTTP MethodURLReturnsNormal response
GET/1.0/usersCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get full details of the user.

HTTP MethodURLReturnsNormal response
GET/1.0/users/(user_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Update request

Update some details of your user profile.

HTTP MethodURLReturnsNormal response
PUT/1.0/users/(user_id)Member200 OK
Parameters
Required Name Type Default Description Example
name String
email_address Email user@example.net
ssh_key String
password Password A password string that conforms to the minimum requirements
password_confirmation Password A password string that conforms to the minimum requirements
Allowed Account states

This action can only be performed when the owning Account is in the following states:

User collaboration

A collaboration forms the link between an Account and a User, giving the User access to the specified Account. User collaborations allow you to list and interact with Collaborations that the specified user has.

States

State Description
pending Collaboration was created and is awaiting acceptence/rejection from the User (via User Collaboration)
accepted Collaboration was accepted and is active
rejected Collaboration was rejected by the user
cancelled Collaboration was deleted before it entered the accepted state
ended Collaboration was accepted but has since been ended by either party

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string CollaborationID col-klek3 true true Unique ID for the collaboration
url string URL true true URL to access details of resource
email string Email user@example.net true true
role string String admin true true Simple and stable name of role
role_label string String Account administrator true true Verbose name of role
status string String false true Current state of the collaboration
created_at string Datetime 2013-04-23T10:40:14Z true true Time of Collaboration creation (UTC)
started_at string Datetime 2013-05-23T10:40:14Z true true Time of Collaboration start (UTC)
finished_at string Datetime 2013-06-23T10:40:14Z true true Time of Collaboration finish (UTC)

Representations

Full User collaboration representation example
{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": null,
 "email": "jjarvis@example.com",
 "role": "admin",
 "created_at": null,
 "started_at": null,
 "finished_at": null,
 "role_label": "Collaborator",
 "user": null,
 "account":
  {"id": "acc-43ks4",
   "resource_type": "account",
   "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
   "name": "Brightbox",
   "status": "active"},
 "inviter":
  {"id": "usr-e8t4w",
   "resource_type": "user",
   "url": "https://api.gb1.brightbox.com/1.0/users/usr-e8t4w",
   "name": "Tom Clock",
   "email_address": "tclock@example.com"}}
Collection User collaboration representation example
[{"id": null,
  "resource_type": "collaboration",
  "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
  "status": null,
  "email": "jjarvis@example.com",
  "role": "admin",
  "created_at": null,
  "started_at": null,
  "finished_at": null,
  "role_label": "Collaborator",
  "user": null,
  "account":
   {"id": "acc-43ks4",
    "resource_type": "account",
    "url": "https://api.gb1.brightbox.com/1.0/accounts/acc-43ks4",
    "name": "Brightbox",
    "status": "active"},
  "inviter":
   {"id": "usr-e8t4w",
    "resource_type": "user",
    "url": "https://api.gb1.brightbox.com/1.0/users/usr-e8t4w",
    "name": "Tom Clock",
    "email_address": "tclock@example.com"}}]
Nested User collaboration representation example
{"id": null,
 "resource_type": "collaboration",
 "url": "https://api.gb1.brightbox.com/1.0/user/collaborations/",
 "status": null,
 "email": "jjarvis@example.com",
 "role": "admin",
 "created_at": null,
 "started_at": null,
 "finished_at": null,
 "role_label": "Collaborator"}

Actions

List request

Lists all collaborations the user is involved with

HTTP MethodURLReturnsNormal response
GET/1.0/user/collaborationsCollection200 OK
Parameters

This action does not have any parameters.

Get request

Shows details of the specified collaboration

HTTP MethodURLReturnsNormal response
GET/1.0/user/collaborations/(user_collaboration_id)Member200 OK
Parameters

This action does not have any parameters.

Accept request

Accepts the collaboration giving access to the account

HTTP MethodURLReturnsNormal response
POST/1.0/user/collaborations/(user_collaboration_id)/acceptMember200 OK
Parameters

This action does not have any parameters.

Reject request

Rejects the collaboration

HTTP MethodURLReturnsNormal response
POST/1.0/user/collaborations/(user_collaboration_id)/rejectMember200 OK
Parameters

This action does not have any parameters.

Delete request

Ends an existing ‘accepted’ collaboration

HTTP MethodURLReturnsNormal response
DELETE/1.0/user/collaborations/(user_collaboration_id)Member200 OK
Parameters

This action does not have any parameters.

Zone

A Zone represents cloud resources at a datacentre. Each Zone is completely isolated in terms of power, cooling, security and networking equipment.

Attributes

Attribute JSON values Type Example Nested? Collected? Description
id string ZoneID zon-8ja0a true true Unique Identifier
url string URL true true URL to access details of resource
handle string String gb1-a true true The Zone handle

Representations

Full Zone representation example
{"id": "zon-328ds",
 "resource_type": "zone",
 "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
 "handle": "gb1"}
Collection Zone representation example
[{"id": "zon-328ds",
  "resource_type": "zone",
  "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
  "handle": "gb1"}]
Nested Zone representation example
{"id": "zon-328ds",
 "resource_type": "zone",
 "url": "https://api.gb1.brightbox.com/1.0/zones/zon-328ds",
 "handle": "gb1"}

Actions

List request

Lists summary details of zones available to the account.

HTTP MethodURLReturnsNormal response
GET/1.0/zonesCollection200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Get request

Get full details of the zone.

HTTP MethodURLReturnsNormal response
GET/1.0/zones/(zone_id)Member200 OK
Parameters

This action does not have any parameters.

Allowed Account states

This action can only be performed when the owning Account is in the following states:

Errors

There are two different styles of errors that the API may return depending on where the problem with the request occurred.

Authentication or access control errors use the OAuth2.0 format. This format provides a single error name and a description.

A single request may contain multiple errors so all errors relating to the API itself will return an error name and an array of errors.

Authentication errors

Requests related to authentication or authorization are implemented as specified in the OAuth2.0 specification.

  HTTP/1.1 400 Bad Request
  WWW-Authenticate: OAuth error="invalid_request"

  {
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed."
  }

As per the specification there is also a “WWW-Authenticate” header that contains the error name as well.

Request errors

When an error occurs for GET or POST requests, the content body includes a JSON object containing details of the error for the client to handle.

  {
      "error_name": "Forbidden",
      "errors": [
          "Account limit reached, please contact support for more information"
      ]
  }

API Errors include more detailed messages where possible without giving out information to unprivileged users.

API ErrorHTTP CodeError summary
Unrecognised endpointBad request (400)The request was for an unrecognised API endpoint
Unauthorized requestUnauthorized (401)The API User doesn’t have permission to access that resource
Account closedForbidden (403)The account has been closed
Account fraudulentForbidden (403)Action prevented due to suspicious activity. Please contact support@brightbox.com
Account limit reachedForbidden (403)Account limit reached
Account not verifiedForbidden (403)The account has not yet been verified
Account suspendedForbidden (403)The account is currently suspended
Account terminatedForbidden (403)The account has been terminated
Account verification pin incorrectForbidden (403)PIN appears to be incorrect
Action forbiddenForbidden (403)The API User is not permitted to carry out requested action
Cloud ip allocation failureForbidden (403)Cloud IP cannot be allocated
Cloud ip release failureForbidden (403)Cloud IP cannot be released
Insufficient capacityForbidden (403)Insufficient capacity available
Insufficient instance capacityForbidden (403)Insufficient server capacity available
Missing resourceNot found (404)Resource not found using supplied identifier
Method not allowedMethod not allowed (405)Invalid HTTP Method
Cloud ip mapping failureConflict (409)Cloud IP cannot be mapped or unmapped
Invalid transitionConflict (409)Unable to action the request due to conflicting states
Resource conflictConflict (409)Unable to action the request due to conflicting states
Snapshot in progressConflict (409)Server snapshot is already underway
Missing associationUnprocessable entity (422)No associated %{resource} found with identifier = %{identifier}
Unprocessable entityUnprocessable entity (422)The request contained errors and could not be completed
Unrecognised parameterUnprocessable entity (422)This parameter is unrecognised: %{parameter}
Internal serverInternal server error (500)Unhandled exception has occured
Not implementedNot implemented (501)This version of the API hasn’t implemented that request