NAV
curl

Overview

This is the official API documentation for the VirtualArctic Cloud.

Introduction

Welcome to the arcticplatform API documentation!

The arcticplatform API allows to manage all of our services. Our API operates over HTTPS and uses JSON as its data format.

As an alternative to working directly with our API you may also consider to use:

API Urls

Our API is always accessible under the Base Url. But for the sandbox/playground we have more urls. You can find them here:

Base URLs - Live (production)

Base URLs - Testing (playground)

Base URLs - Staging (sandbox)

The API is only accessible via HTTPS.

Customers not from Europe can use a different API than customers in Europe. We route the requests to a server that is closer to the customer.

If you got a different API url from our team, please use your own.

Rate Limiting

All our requests to the arcticplatform API are counted. If the limit for your account is reached, the error 429 Too Many Requests is thrown.

The limit for our API is set to 36.000 per hour by default. This limit allows you to send 10 requests per second to our API. There is no limit per second/minute. The limit can also be adjusted per account, please contact our team for more information.

In the HTTP headers you will find the following information about the API requests:

Data Types

Strings

Strings may be up to 255 characters, unless otherwise noted in the field description.

Dates

Dates are expressed according to the ISO_8601 standard with combined date, time and timezone. We support milliseconds. One example is 2020-08-28T18:55:00Z representing the 28th of August 2020 at 18:55:00 and the UTC timezone.

Location & Countries

Locations used IATA codes to identify the location.

Countries used ISO 3166-1 alpha-2 code of the country the Location resides in

Encoding

We expect all data that is sent to our APIs to be UTF-8 encoded.

Errors

The arcticplatform API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The arcticplatform requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Quick Start Guide

TBD

Authentication

Create a new Account

Creates a new account. After creation an e-mail is sent to the specified e-mail. After confirmation of the e-mail the account is activated and you can login.

HTTP Request

POST /v1/auth/register

To create a new arcticplatform Account, use this code:

curl -X POST \  
     -H "Content-Type: application/json" \
     -d '{"name":"Giuliano Schindler","email":"cloud@arctic.sh","password":"fridge"}' \
     'https://api.arcticplatform.com/v1/auth/register'

Request

{
    "name": "Giuliano Schindler",
    "email": "cloud@arctic.sh",
    "password": "fridge"
}

Response sample

{
    "token": "xxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600
}

Request

Name Description
name string required
Your first and lastname or company name
email string required
The email address of you new arcticplatform account
password string required
The password of you new arcticplatform account

Create a Token

Our API can be used with the standard login or you can use an App Token for your applications.

Here we show how to create an API token from the default Login.

HTTP Request

POST /v1/auth/login

Request

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"email":"cloud@arctic.sh","password":"fridge"}' \
     'https://api.arcticplatform.com/v1/auth/login'

Response sample

{
    "token": "xxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600
}

Request

Name Description
email string required
The email address of your arcticplatform account
password string required
The password of your arcticplatform account

Delete the current token

If you did not use an AppToken to login to the API, you can end the current session.

HTTP Request

POST /v1/auth/logout

Request

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ARCTIC_API_TOKEN" \
     "https://api.arcticplatform.com/v1/auth/logout"

Make sure to replace $ARCTIC_API_TOKEN with your API key.

Response

{
    "message": "Successfully logged out"
}

No parameters needed for these request.

Baremetal Servers

Name Description
billingPeriod string
Specifies the period in which the server is to be billed. Available periods: Hourly, Monthly, Quarterly, Semiannually, Annually.
bmcType string
Can be dedicated, onboard or hybrid. hybrid means that the server has a Telejet Webresetter.
bmcName string
Can be IPMI, iLO or Telejet.
bandwidthType string
Our Traffic classes are: Premium, Low-Latency, Global-routing, Local-routing or Fair-use
sla string
Our SLA are: Basic, Premium or Enterprise.

Get Baremetal Server Plans

curl -X GET \
     -H "Content-Type: application/json" \
     'https://api.arcticplatform.com/v1/baremetal/plans'

Response

{
  "baremetals":{
    "E3-1230v2":{
      "id":"c2d4b948-6176-486b-b9eb-681abb911001",
      "model":"E3-1230v2",
      "category":"dedicated",
      "pricing":[
        {
          "priceGross":3.966666667,
          "priceNet":3.333333333,
          "currencyCode":"EUR",
          "unit":"Hourly"
        },
        {
          "priceGross":119.00,
          "priceNet":100.00,
          "currencyCode":"EUR",
          "unit":"Monthly"
        },
        {
          "priceGross":357.00,
          "priceNet":300.00,
          "currencyCode":"EUR",
          "unit":"Quarterly"
        },
        {
          "priceGross":1071.00,
          "priceNet":600.00,
          "currencyCode":"EUR",
          "unit":"Semiannually"
        },
        {
          "priceGross":1428.00,
          "priceNet":1200.00,
          "currencyCode":"EUR",
          "unit":"Annually"
        }
      ],
      "specs":{
        "vendor":"Supermicro",
        "cpus":{
          "count":1,
          "family":"E3",
          "generation":"1230",
          "version":2,
          "vendor":"Intel",
          "fullName":"Intel Xeon E3-1230v2",
          "cores":4,
          "threads":8,
          "frequency":3.3,
          "burstFrequency":3.7,
          "unit":"GHz"
        },
        "memory":{
          "count":1,
          "total":32,
          "unit":"GB",
          "name":"32GB DDR3 ECC",
          "ecc":true
        },
        "drives":[
          {
            "count":1,
            "name":"SSD 120GB",
            "size":120,
            "unit":"GB",
            "type":"SSD",
            "enterprise":true
          }
        ],
        "raid":{
          "name":"Raid 1"
        },
        "nics":[
          {
            "count":1,
            "name":"1x 1Gbps",
            "vendor":"onboard"
          }
        ],
        "bandwidth":{
          "name":"5TB",
          "type": "premium"
        },
        "bmc":{
          "name":"IPMI",
          "type":"dedicated"
        },
        "sla": {
          "name": "Basic"
        },
        "customizable":false
      },
      "stocks":[
        {
          "id":"d8be4964-5a3c-4f91-9def-9111d91a4e1a",
          "name":"EU (Frankfurt)",
          "slug":"de-south-1",
          "available":true,
          "is_default":true,
          "description":"Frankfurt, Germany",
          "stock":20,
          "availability_zones":[
            {
              "id":"144a7f20-6de1-4871-b592-dc443e34e146",
              "name":"Zone A",
              "slug":"de-south-1a",
              "available":true,
              "is_default":false,
              "description":null,
              "region_id":"d8be4964-5a3c-4f91-9def-9111d91a4e1a",
              "stock":10
            }
          ]
        }
      ]
    }
  }
}

Returns all available Baremetal Servers

HTTP Request

GET /v1/baremetal/plans

Name Description
id uuid
A unique identifier for each server instance. This is automatically generated upon server creation.
category string
The value can be dedicated, blade or business-server
pricing object
The "pricing" object shows the prices for the different periods.
specs object
The "specs" object shows all hardware configurations of the baremetal server.
stocks object
The "stocks" that the Baremetal Server instalce can deployed in and shows the number of available instances.

Create a Baremetal Server

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ARCTIC_API_TOKEN" \
     -d '{ "id": "c2d4b948-6176-486b-b9eb-681abb911001", "serverCategory": "blade", "billingPeriod": "Monthly", "region": "d8be4964-5a3c-4f91-9def-9111d91a4e1a", "availabilityZone": "144a7f20-6de1-4871-b592-dc443e34e146", "name": "jelly-fish.arctic.sh", "alias": "server.example.com" }' \
     'https://api.arcticplatform.com/v1/baremetal'

Make sure to replace $ARCTIC_API_TOKEN with your API key.

Request

{
  "id": "c2d4b948-6176-486b-b9eb-681abb911001",
  "serverCategory": "blade",
  "billingPeriod": "Monthly",
  "region": "d8be4964-5a3c-4f91-9def-9111d91a4e1a",
  "availabilityZone": "144a7f20-6de1-4871-b592-dc443e34e146",
  "name": "jelly-fish.arctic.sh",
  "alias": "server.example.com"
}

Response

{
  "baremetal": {
    "id": "016d3bdf-79ef-4bb0-aff4-276a4627b8bc",
    "state": "purchase-in-queue"
  }
}

Order a Baremetal server by API.

HTTP Request

POST /v1/baremetal

Request Body

Name Description
id uuid REQUIRED
The server id to be purchased.
serverCategory string REQUIRED
The value can be dedicated, blade or business-server.
billingPeriod string REQUIRED
Specifies the period in which the server is to be billed. Available periods: Hourly, Monthly, Quarterly, Semiannually, Annually.
region uuid REQUIRED
Region where the server should be deployed.
availabilityZone uuid OPTIONAL
Availability Zone where the server should be deployed. (If no Availability Zone given, server wil be deployed in default Availability Zone.)
name string OPTIONAL
Name of the Server to create (must be unique and a valid hostname as per RFC 1123)
alias string OPTIONAL
An alias for the server. The field can have a maximum of 255 characters.

Get all Baremetal Server

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ARCTIC_API_TOKEN" \
     'https://api.arcticplatform.com/v1/baremetal'

Make sure to replace $ARCTIC_API_TOKEN with your API key.

Response

{
  "baremetals":[
    {
      "model":"E3-1230v2",
      "name":"jelly-fish.arctic.sh",
      "category":"dedicated",
      "state":"active",
      "plan":{
        "specs":{
          "vendor":"Supermicro",
          "cpus":{
            "count":1,
            "family":"E3",
            "generation":"1230",
            "version":2,
            "vendor":"Intel",
            "fullName":"Intel Xeon E3-1230v2",
            "cores":4,
            "threads":8,
            "frequency":3.3,
            "burstFrequency":3.7,
            "unit":"GHz"
          },
          "memory":{
            "count":1,
            "total":32,
            "unit":"GB",
            "name":"32GB DDR3 ECC",
            "ecc":true
          },
          "drives":[
            {
              "count":1,
              "name":"SSD 120GB",
              "size":120,
              "unit":"GB",
              "type":"SSD",
              "enterprise":true
            }
          ],
          "raid":{
            "name":"Raid 1"
          },
          "nics":[
            {
              "count":1,
              "name":"1x 1Gbps",
              "vendor":"onboard"
            }
          ],
          "bandwidth":{
            "name":"5TB",
            "type":"premium"
          },
          "bmc":{
            "name":"IPMI",
            "type":"dedicated"
          },
          "sla": {
            "name": "Basic"
          },
          "customizable":false
        }
      },
      "pricing":{
        "priceGross":3.966666667,
        "priceNet":3.333333333,
        "currencyCode":"EUR",
        "unit":"Hourly",
        "quantity":2,
        "billableAmountNet":6.666666666,
        "billableAmountGross":7.933333334
      },
      "ipAddresses":[
        {
          "id":"e605c1f6-b659-4e50-9605-d36605bd874e",
          "address":"xxx.xxx.xxx.xxx",
          "address_family":4,
          "cidr":"xxx.xxx.xxx.xxx/xx",
          "gateway":"xxx.xxx.xxx.xxx",
          "type":"primary-ip",
          "ptrRecord":"",
          "specrtumScrubbing":false
        }
      ],
      "region":[
        {
          "id":"d8be4964-5a3c-4f91-9def-9111d91a4e1a",
          "name":"EU (Frankfurt)",
          "slug":"de-south-1",
          "available":true,
          "is_default":true,
          "description":"Frankfurt, Germany",
          "availability_zones":[
            {
              "id":"144a7f20-6de1-4871-b592-dc443e34e146",
              "name":"Zone A",
              "slug":"de-south-1a",
              "available":true,
              "is_default":false,
              "description":null,
              "region_id":"d8be4964-5a3c-4f91-9def-9111d91a4e1a"
            }
          ]
        }
      ],
      "tags":{

      },
      "terminationDate":false,
      "createdAt":"2020-08-30T14:03:36Z"
    }
  ]
}

List all Baremetals server

HTTP Request

GET /v1/baremetal

Get a Baremetal Server

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ARCTIC_API_TOKEN" \
     'https://api.arcticplatform.com/v1/baremetal/{baremetalId}'

Make sure to replace $ARCTIC_API_TOKEN with your API key.

Response

{
  "baremetal":{
    "model":"E3-1230v2",
    "name":"jelly-fish.arctic.sh",
    "category":"dedicated",
    "state":"active",
    "plan":{
      "specs":{
        "vendor":"Supermicro",
        "cpus":{
          "count":1,
          "family":"E3",
          "generation":"1230",
          "version":2,
          "vendor":"Intel",
          "fullName":"Intel Xeon E3-1230v2",
          "cores":4,
          "threads":8,
          "frequency":3.3,
          "burstFrequency":3.7,
          "unit":"GHz"
        },
        "memory":{
          "count":1,
          "total":32,
          "unit":"GB",
          "name":"32GB DDR3 ECC",
          "ecc":true
        },
        "drives":[
          {
            "count":1,
            "name":"SSD 120GB",
            "size":120,
            "unit":"GB",
            "type":"SSD",
            "enterprise":true
          }
        ],
        "raid":{
          "name":"Raid 1"
        },
        "nics":[
          {
            "count":1,
            "name":"1x 1Gbps",
            "vendor":"onboard"
          }
        ],
        "bandwidth":{
          "name":"5TB",
          "type":"premium"
        },
        "bmc":{
          "name":"IPMI",
          "type":"dedicated"
        },
        "sla": {
          "name": "Basic"
        },
        "customizable":false
      }
    },
    "pricing":{
      "priceGross":3.966666667,
      "priceNet":3.333333333,
      "currencyCode":"EUR",
      "unit":"Hourly",
      "quantity":2,
      "billableAmountNet":6.666666666,
      "billableAmountGross":7.933333334
    },
    "ipAddresses":[
      {
        "id":"e605c1f6-b659-4e50-9605-d36605bd874e",
        "address":"xxx.xxx.xxx.xxx",
        "address_family":4,
        "cidr":"xxx.xxx.xxx.xxx/xx",
        "gateway":"xxx.xxx.xxx.xxx",
        "type":"primary-ip",
        "ptrRecord":"",
        "specrtumScrubbing":false
      }
    ],
    "region":[
      {
        "id":"d8be4964-5a3c-4f91-9def-9111d91a4e1a",
        "name":"EU (Frankfurt)",
        "slug":"de-south-1",
        "available":true,
        "is_default":true,
        "description":"Frankfurt, Germany",
        "availability_zones":[
          {
            "id":"144a7f20-6de1-4871-b592-dc443e34e146",
            "name":"Zone A",
            "slug":"de-south-1a",
            "available":true,
            "is_default":false,
            "description":null,
            "region_id":"d8be4964-5a3c-4f91-9def-9111d91a4e1a"
          }
        ]
      }
    ],
    "tags":{

    },
    "terminationDate":false,
    "createdAt":"2020-08-30T14:03:36Z"
  }
}

Get a Baremetal server

HTTP Request

GET /v1/baremetal/{baremetalId}

Regions

Get All Regions

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ARCTIC_API_TOKEN" \
     "https://api.arcticplatform.com/v1/regions"

Response

{
  "regions": [
    {
      "id": "d8be4964-5a3c-4f91-9def-9111d91a4e1a",
      "name": "EU (Frankfurt)",
      "slug": "de-south-1",
      "available": true,
      "isDefault": true,
      "description": "Frankfurt, Germany",
      "availabilityZones": [
        {
          "id": "144a7f20-6de1-4871-b592-dc443e34e146",
          "name": "Zone A",
          "slug": "de-south-1a",
          "available": true,
          "isDefault": false,
          "description": null,
          "regionId": "d8be4964-5a3c-4f91-9def-9111d91a4e1a"
        }
      ]
    }
  ]
}

Returns all existing region objects.

HTTP Request

GET /v1/regions

Get a Region

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ARCTIC_API_TOKEN" \
     "https://api.arcticplatform.com/v1/regions/{regionId}"

Make sure to replace $ARCTIC_API_TOKEN with your API key.

Response

{
  "regions": [
    {
      "id": "d8be4964-5a3c-4f91-9def-9111d91a4e1a",
      "name": "EU (Frankfurt)",
      "slug": "de-south-1",
      "available": true,
      "is_default": true,
      "description": "Frankfurt, Germany",
      "availabilityZones": [
        {
          "id": "144a7f20-6de1-4871-b592-dc443e34e146",
          "name": "Zone A",
          "slug": "de-south-1a",
          "available": true,
          "is_default": false,
          "description": null,
          "regionId": "d8be4964-5a3c-4f91-9def-9111d91a4e1a"
        }
      ]
    }
  ]
}

Returns a existing region objects.

HTTP Request

GET /v1/regions/{regionId}

Query Parameters

Name Description
regionId uuid
The uuid of an existing region

Get All Available Zones of a Region

curl -X GET \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $ARCTIC_API_TOKEN" \
     "https://api.arcticplatform.com/v1/regions/{regionId}/availableZones"

Make sure to replace $ARCTIC_API_TOKEN with your API key. Response

{
  "availabilityZones": [
    {
      "id": "144a7f20-6de1-4871-b592-dc443e34e146",
      "name": "Zone A",
      "slug": "de-south-1a",
      "available": true,
      "isDefault": false,
      "description": null,
      "regionId": "d8be4964-5a3c-4f91-9def-9111d91a4e1a"
    }
  ]
}

Returns all existing region objects.

HTTP Request

GET /v1/regions/{regionId}/availableZones

Query Parameters

Name Description
regionId string
The uuid of an existing region
curl