NAV Navbar
cURl JavaScript
  • API Documentation
  • Introduction
  • Servers
  • Storages
  • Networks
  • IP Addresses
  • Firewalls
  • ISO Images
  • SSH Keys
  • Locations
  • Object Storages
  • Deleted
  • Cloud Automation
  • PaaS
  • API Documentation

    Version: v1

    Supported media type: application/json

    Supported protocols: HTTPS

    API Base URI: https://api.gridscale.io/objects

    API resources:

    Resource Description
    Servers The general endpoint for servers. Here you can query GET - to receive a list of all your servers, POST - to create a new servers and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    Storages The general endpoint for storages. Here you can query GET - to receive a list of all your storages, POST - to create a new storage and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    Networks The general endpoint for networks. Here you can query GET - to receive a list of all your networks, POST - to create a new network and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    Ips The general endpoint for IP Addresses. Here you can query GET - to receive a list of all your IP Addresses, POST - to create a new IP Address and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    Firewalls The general endpoint for Firewalls. Here you can query GET - to receive a list of all your Firewalls, POST - to create a new Firewall and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    ISO Images The general endpoint for ISO-Images. Here you can query GET - to receive a list of all your ISO-Images, POST - to create a new ISO-Images and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    SSH Keys The general endpoint for SSH keys. Here you can query GET - to receive a list of all your SSH keys, POST - to create a new SSH key and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    Locations The general endpoint for locations. Here you can query GET - to receive a list of all your locations and OPTIONS - to receive a detailed list of all the possible actions for the endpoint.
    ObjectStorages Object storages store your access keys and buckets.
    Deleted Objects that are deleted are no longer visible on their regular endpoints. For historical reasons these objects are still available read-only on a special endpoint named /deleted. If objects have been deleted but have not yet been billed in the current period, the yet-to-be-billed price is still shown.
    Cloud Automation Cloud Automation helps you to automate your infrastructure through notifications, so you can keep on top of what's happening.
    Platform Services Our Platform Services allow you to create and setup a backend service in no time. You can choose from MySQL, PostgreSQL or Redis at varying application sizes.

    Introduction

    Welcome to gridscale's API documentation.

    REST API is a programming interface that allows you to access and send data directly to the provisioning system using HTTPS requests, without the need to use a web GUI. All the functionality you are already familiar with in your control panel is accessible through the API, including a lot of expert methods that are only available through the API. Allowing you to script any actions you require, regardless of their complexity.

    First we will start with a general overview about how the API works, followed by an extensive list of each endpoint, describing them in great detail.

    Authentication

    To authorize, use this code:

    // to get started
    // read the docs @ https://www.npmjs.com/package/@##gridscale/api
    var ##gridscale = require('@##gridscale/api').##gridscale;
    var client = new ##gridscale.Client("##API-Token##","##User_UUID##");
    
        -H "X-Auth-UserId: ##User_UUID##" \
        -H "X-Auth-Token: ##API-Token##" \
      # Make sure to replace `User_UUID` and `API-Token`
      # with your personal UUID and API key respectively.
    

    In order to use the API, the User-UUID and an API-Token are required. Both are available via the web GUI which can be found here on Your Account

    The User-UUID is always the same for a user, even if the email address is changed. The API-Token is a random generated hash that can allow read/write access.

    NodeJs Library

    Using cURL can be cumbersome and not always everyones first choice, so we created a JavaScript library for you to use our API with ease.

    npm badge

    Requests with our NodeJs lib return a little differently. Don't worry, everything is the same except it allows you to add URL parameters to customize your requests.

    To get started, set the language tab to JavaScript, at the top right of your screen (for mobile users: open the menu to change languages), and click here .

    Requests

    For security, gridscale requires all API requests are made through the HTTPS protocol so that traffic is encrypted. The following table displays the different type of requests that the interface responds to, depending on the action you require.

    Method Description
    GET A simple search of information. The response is a JSON object. Requests using GET are always read-only.
    POST Adds new objects and object relations. The POST request must contain all the required parameters in the form of a JSON object.
    PATCH Changes an object or an object relation. The parameters in PATCH requests are usually optional, so only the changed parameters must be specified in a JSON object.
    DELETE Deletes an object or object relation. The object is deleted if it exists.
    OPTIONS Get an extensive list of the servers support methods and characteristics. We will not give example OPTION requests on each endpoint, as they are extensive and self-descriptive.

    Status Codes

    HTTP Status Message Description
    200 OK The request has been successfully processed and the result of the request is transmitted in the response.
    202 Accepted The request has been accepted, but will run at a later date. The success of the request can not be guaranteed.
    204 No Content The request was successful, but the answer deliberately contains no data.
    400 Bad Request The request message was built incorrectly.
    401 Unauthorised The request can not be performed without a valid authentication. X-Auth UserId or X-Auth token HTTP header is not set or the userID / token is invalid.
    402 Payment Required Action can not be executed - not provided any or invalid payment methods.
    403 Forbidden The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
    404 Not Found The requested resource was not found. Will also be used if you do a resource exists, but the user does not have permission for it.
    405 Method Not Allowed The request may be made only with other HTTP methods (eg GET rather than POST).
    409 Conflict The request was made under false assumptions. For example, a user can not be created twice with the same email.
    415 Unsupported Media Type The contents of the request have been submitted with an invalid media type. All POST or PATCH requests must have "Content-Type : application / json" as a header, and send a JSON object as a payload.
    424 Failed Dependency The request could not be performed because the object is in the wrong status.

    Request Headers

    Header Description
    Content-Type Always "applicaton/json".
    X-Auth-userId The user UUID. This can be found in the panel under "API" and will never change ( even after the change of user e-mail).
    X-Auth-Token is generated from the API hash and must be sent with all API requests. Both the token and its permissions can be configured in the panel.

    Response Headers

    Header Description
    Content-Type Always "application/json".
    X-Exec-Time The time that provisioning has used internally to process the request (in ms).
    X-Api-Version The currently active Provisioning API version. Useful when reporting bugs to us.

    Timestamp Format

    All timestamps follow ISO 8601 and issued in UTC

    CORS

    Cross Origin Resource Sharing

    To allow API access from other domains that supports the API CORS (Cross Origin Resource Sharing). See: enable-cors.org/ .

    This allows direct use the API in the browser running a JavaScript web control panel.

    All this is done in the background by the browser. The following HTTP headers are set by the API:

    Header Description
    Access Control-Allow-Methods GET, POST, PUT, PATCH, DELETE, OPTIONS
    Access-Control-Allow-Credentials Is set to "true". Allows the browser to send the authentication data via X-Auth HTTP header.
    Access-Control-Allow-Headers Origin, X-Requested-With, Content-Type, Accept, X-Auth-UserId, X-Auth-Token, X-Exec-Time, X-API-Version, X-Api-Client
    Content-Type "application/json"
    Allow The allowed control methods on this endpoint.
    X-Auth UserId The UUID of the user who created the request
    X-Auth token The unique token of the user who created the request
    X-Api version The available for inquiries HTTP header.
    Access-Control-Allow-Origin The domain sent by the browser as a source of demand.
    X-Api version The HTTP headers that can be used by a browser application.

    Object relations

    Relationships describe resource objects (storages, networks, IPs, etc.) that are connected to a server. These relationships are treated like objects themselves and can have properties specific to this relation.

    One example would be, that the MAC address of a private network connected to a server (Server-to-Network relation) can be found as property of the relation itself - the relation is the network interface card in the server.

    Another example is storage, where the SCSI LUN is also part of the Server-to-Storage relation object.

    This information is especially interesting if some kind of network boot is used on the servers, where the properties of the server need to be known beforehand.

    Deleted Objects

    Objects that are deleted are no longer visible on their regular endpoints. For historical reasons these objects are still available read-only on a special endpoint named /deleted. If objects have been deleted but have not yet been billed in the current period, the yet-to-be-billed price is still shown.

    Servers

    Our high performance cloud servers are ready within milliseconds. They are the basis of launching your application, and we make them as flexible as possible to exactly match your infrastructure to your needs. Even the most complex server infrastructures can be set up via our API.

    Updating a server is even easier with our innovative hot-plug technology, you can increase the resources of your servers at any time without having to shut down the server.

    This section will help you to manage your infrastructure via our RESTful API.

    Servers Get

    You can use this command to get a list of all your servers

    client.Server.list().then(function( res ) {
        console.log(res.result.servers);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers
    

    The above command returns a JSON object structured like this

    {
        "servers": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "auto_recovery": true,
                "availability_zone": null,
                "current_price": 9.491665,
                "power": true,
                "status": "active",
                "cores": 1,
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "name": "Ubunto 16.04",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "usage_in_minutes_cores": 17476,
                "labels": [],
                "hardware_profile": "default",
                "location_iata": "fra",
                "location_name": "de/fra",
                "legacy": false,
                "memory": 2,
                "create_time": "2018-03-14T13:33:13Z",
                "relations": {
                    "public_ips": [
                        {
                            "prefix": "1x:12:xx:12:12:12/32",
                            "create_time": "2018-03-14T13:33:14Z",
                            "family": 4,
                            "ip": "123.123.12.1",
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
                        },
                        {
                            "prefix": "123.123.12.1/128"
                            "create_time": "2018-03-14T13:33:16Z",
                            "family": 6,
                            "ip": "123.123.12.1",
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
                        }
                    ],
                    "isoimages": [],
                    "networks": [
                        {
                            "bootdevice": false,
                            "firewall_template_uuid": null,
                            "vlan": null,
                            "mcast": null,
                            "vxlan": null,
                            "public_net": true,
                            "l2security": true,
                            "object_name": "Public Network test",
                            "network_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "create_time": "2018-03-14T13:33:13Z",
                            "firewall": null,
                            "network_type": "network",
                            "mac": "16:f7:22:9e:56:01",
                            "partner_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "l3security": [],
                            "ordering": 0,
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
                        }
                    ],
                    "storages": [
                        {
                            "bootdevice": true,
                            "target": 0,
                            "lun": 0,
                            "capacity": 11,
                            "object_name": "Ubunto 16.04 Storage",
                            "controller": 0,
                            "create_time": "2018-03-14T13:33:24Z",
                            "storage_type": "storage",
                            "bus": 0,
                            "last_used_template": "ec4ef18f-84df-42bb-b7c4-c2957635ee53",
                            "license_product_no": null,
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
                        }
                    ]
                },
                "usage_in_minutes_memory": 47331,
                "change_time": "2018-03-19T11:40:55Z",
                "console_token": "$console_token",
                "location_country": "de"
            }
        }
    }
    

    GET https://api.gridscale.io/objects/servers

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters
    labels array[string] List of labels for this server - allows you to group objects into projects.
    cores integer Number of server cores
    memory integer Indicates the amount of memory in GB.
    status string Defines the status of the server - 'active', 'in-provisioning' etc
    create_time datatime The date and time the server was created
    change_time datatime The date and time that the server was last edited
    location_uuid string The UUID of the datacenter that this server belongs to
    location_name string The human readable name of the datacenter that this server belongs to
    location_country string The coutry code hosting this server in ISO 3266-2 format
    location_iata string IATA airport code for the country, works as a location identifier
    console_token string The token used by the panel to open the websocket VNC connection to the server console
    legacy boolean Legacy-Hardware emulation instead of virtio hardware. If enabled, hotplugging cores, memory, storage, network, etc. will not work, but the server will most likely run every x86 compatible operating system. This mode comes with a performance penalty, as emulated hardware does not benefit from the virtio driver infrastructure
    availability_zone string Which Availability-Zone the Server is placed
    auto_recovery boolean If the server should be auto-started in case of a failure (default=true).
    current_price number The price for the current period since the last bill
    relations array[object] Objects related to this server

    Server Get

    You can use this command to get a list of all your servers

    client.Server.get("2d850e53-75e4-4c5c-954b-2757ec46315e").then(function( res ) {
        console.log(res.result.server);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}
    

    The above command returns a JSON object structured like this

    {
        "server": {
            "cores": 1,
            "relations": {
                "storages": [
                    {
                        "capacity": 11,
                        "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "last_used_template": "ec4ef18f-84df-42bb-b7c4-c2957635ee53",
                        "controller": 0,
                        "license_product_no": null,
                        "bus": 0,
                        "target": 0,
                        "create_time": "2018-03-14T13:33:24Z",
                        "lun": 0,
                        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "bootdevice": true,
                        "object_name": "Ubunto 16.04 Storage",
                        "storage_type": "storage"
                    }
                ],
                "public_ips": [
                    {
                        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "prefix": "1x:12:xx:12:12:12/32",
                        "ip": "123.123.12.1",
                        "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "create_time": "2018-03-14T13:33:14Z",
                        "family": 4
                    },
                    {
                        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "prefix": "123.123.12.1/128",
                        "ip": "123.123.12.1",
                        "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "create_time": "2018-03-14T13:33:16Z",
                        "family": 6
                    }
                ],
                "networks": [
                    {
                        "network_type": "network",
                        "vlan": null,
                        "create_time": "2018-03-14T13:33:13Z",
                        "ordering": 0,
                        "bootdevice": false,
                        "mac": "16:f7:22:9e:56:01",
                        "vxlan": null,
                        "mcast": null,
                        "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "l3security": [],
                        "firewall_template_uuid": null,
                        "partner_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "object_name": "Public Network test",
                        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "network_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "public_net": true,
                        "firewall": null,
                        "l2security": true
                    }
                ],
                "isoimages": []
            },
            "legacy": false,
            "memory": 2,
            "console_token": "$console_token",
            "usage_in_minutes_memory": 47331,
            "auto_recovery": true,
            "create_time": "2018-03-14T13:33:13Z",
            "current_price": 9.491665,
            "location_country": "de",
            "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
            "usage_in_minutes_cores": 0,
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "change_time": "2018-03-19T11:40:55Z",
            "availability_zone": null,
            "location_iata": "fra",
            "labels": [],
            "hardware_profile": "default",
            "location_name": "de/fra",
            "power": true,
            "name": "Ubunto 16.04",
            "status": "active"
        }
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}

    To receive detailed information regarding a specific server, just append the server_uuid onto the /servers endpoint.

    Response

    Parameter type Description
    object_uuid (required) string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array[string] List of labels.
    cores integer The number of server cores.
    memory integer The amount of server memory in GB.
    status string The status of the object.
    create_time datatime The date and time the object was initially created.
    change_time datatime The date and time of the last object change.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    console_token string Defines the token used by the panel to open the websocket VNC connection to the server console.
    legacy boolean Legacy-Hardware emulation instead of virtio hardware. If enabled, hotplugging cores, memory, storage, network, etc. will not work, but the server will most likely run every x86 compatible operating system. This mode comes with a performance penalty, as emulated hardware does not benefit from the virtio driver infrastructure.
    availability_zone string Defines which Availability-Zone the Server is placed.
    auto_recovery boolean If the server should be auto-started in case of a failure (default=true).
    current_price number The price for the current period since the last bill.
    relations array[object] Objects related to this Server

    Server Create

    Example Request

    client.Server.create({name:"example server", cores:1, memory: 2, location_uuid:"45ed677b-3702-4b36-be2a-a2eab9827950"}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "example server" ,"cores": 1, "memory": 2, "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"}' \
         -X POST \
         https://api.gridscale.io/objects/servers
    

    Example Request Body

    {
      "name": "example server",
      "cores": 1,
      "memory": 2,
      "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"
    }
    

    Example Response

    {
        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
        "request_uuid": "690de890-13c0-4e76-8a01-e10ba8786e53"
    }
    

    POST https://api.gridscale.io/objects/servers

    Creating a simple server with our API is easy, you can use the code to the right, to create a server.

    Request

    A full list of the possible Parameters for the body of your request

    Parameter type required Description
    location_uuid string required The UUID of the datacenter you would like to hold your server. A list of available data centres can be found with a GET request on the /locations endpoint.
    name string required The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array[string] List of labels.
    cores integer required The number of server cores.
    memory integer required The amount of server memory in GB.
    status string The status of the object.
    availability_zone string Defines which Availability-Zone the Server is placed.
    auto_recovery boolean If the server should be auto-started in case of a failure (default=true).

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object. You can use this UUID to further refer to the newly created server
    request_uuid string The UUID of the request, so you can reference it later.

    Server Patch

    Example Request

    client.Server.patch("2d850e53-75e4-4c5c-954b-2757ec46315e", {name: "Updated Name"}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "Updated Name"}' \
         -X PATCH \
         https://api.gridscale.io/objects/servers/{server_uuid}
    

    Example Request Body

    {
      "name": "Updated Name"
    }
    

    PATCH https://api.gridscale.io/objects/servers/{server_uuid}

    Updating a server with our API is easy, you can use the code to the right, to rename a server, and much more by adding new parameters to your request.

    Request

    A full list of the possible Parameters for the body of your request

    Parameter type Description
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array[string] List of labels.
    cores integer The number of server cores.
    memory integer The amount of server memory in GB.
    availability_zone string Defines which Availability-Zone the Server is placed.
    auto_recovery boolean If the server should be auto-started in case of a failure (default=true).

    Response

    The server will respond with 204, and an empty body - meaning the update was successful.

    Server Delete

    Example Request

    client.Server.remove("a891ccc0-c013-4112-9fce-008344151d22").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/servers/{server_uuid}
    

    Example response headers

    ...
    HTTP/1.1 204 No Content
    ...
    

    DELETE https://api.gridscale.io/objects/servers/{server_uuid}

    To Delete a server, just append the server_uuid onto the /servers endpoint and send a DELETE request along with your authentication credentials

    Response

    The server will respond with 204, and an empty body - meaning the update was successful.

    Server Events

    Example Request

    client.Server.events("2d850e53-75e4-4c5c-954b-2757ec46315e").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/events
    

    Example Response

     {
         "events": [
            {
                "request_uuid": "9f1b47da-4251-495c-a879-38a290aa65fa",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "timestamp": "2018-02-20T11:51:20Z",
                "request_status": "done",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "object_type": "server",
                "activity": "dhcp_add",
                "request_type": "server_relation_ipaddr_add",
                "change": "Add ip relation to server test"
            }, "...": {
            }
      ]
     }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/events

    Request

    The events endpoint for a server, returns a list of all the events on that object. You can alternatively find them as "Audit Logs" in your expert panel.

    Response

    Parameter Type Description
    request_uuid string The UUID of the event.
    user_uuid string The UUID of the user that triggered the event.
    timestamp datatime Time the event was triggered.
    request_status boolean True or false, whether the request was successful or not.
    object_uuid string The UUID of the objects the event was executed on.
    object_type string Type of object "server, storage, IP" etc.
    activity string The type of change.
    request_type string The type of request.
    change string A detailed description of the change.

    Power Status

    Example request

    // coming soon
    
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/power
    

    Example response

    {
        "power": true
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/power

    To find out the status of your sever just send a GET request to the /power endpoint for the specified server.

    Server On/Off

    Example request

    client.Server.power("2d850e53-75e4-4c5c-954b-2757ec46315e", false).then(function( res ) {
        console.log(res.success);
        // res.success will indicate whether the action was successful.
        // so for turning a server on & off, both responses will be "true"
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"power": true}' \
         -X PATCH \
         https://api.gridscale.io/objects/servers/{server_uuid}/power
    

    Example request body

    {
        "power": true
    }
    

    PATCH https://api.gridscale.io/objects/servers/{server_uuid}/power

    Example bad response

    {
        "status": "400 Bad Request",
        "message": "Server  x123xx1x-123x-1x12-123x-123xxx123x1x is already in the requested power state (power=False)"
    }
    

    Request

    To turn on and off a server, we need to send a PATCH request to the /power endpoint, with a JSON object, defining the status we want. If power = true, the server will be turned on, and visa-versa.

    Response

    A successful request will return a 204 response with no body.

    Linked IP's Get

    You can use this command to get a list of all the IP Addresses linked to a server

    // coming soon
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/ips
    

    Example response

    {
        "ip_relations": [
            {
                "ip": "123.123.12.1",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "create_time": "2018-02-20T11:51:17Z",
                "family": 4,
                "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "prefix": "123.123.12.1/32"
            }, "...": {
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/ips

    Response

    Parameter type Description
    ip string The IP Address (v4 or v6)
    object_uuid string The UUID of the IP Address
    create_time datatime The time that the IP was created
    family integer Either 4 or 6
    server_uuid string The UUID of the server that this IP is attached to.
    prefix string The prefix of the IP Address.

    Linked IP Get

    You can use this command to get an IP Address linked to a server

    client.Server.ip("2d850e53-75e4-4c5c-954b-2757ec46315e", "x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.result.ip_relation);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##"
         -H "X-Auth-Token: ##API-Token##"
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/ips/{ip_uuid}
    

    Example response

    {
        "ip_relation": {
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "family": 4,
            "ip": "123.123.12.1",
            "prefix": "123.123.12.1/32",
            "create_time": "2018-03-09T16:17:46Z"
        }
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/ips/{ip_uuid}

    Request

    URI Parameter type Description
    server_uuid string The UUID of the server, that relates to the IP you are requesting.
    ip_uuid string The UUID of the IP Address you're requesting.

    Response

    Parameter type Description
    ip string The IP Address (v4 or v6)
    object_uuid string The UUID of the IP Address
    create_time datatime The time that the IP was created
    family integer Either 4 or 6 meaning v4 or v6 respectively
    prefix string The prefix of the IP Address.

    You can use this command to get a list of all the IP Addresses linked to a server

    client.Server.addIp("2d850e53-75e4-4c5c-954b-2757ec46315e", "x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"}' \
         -X POST \
         https://api.gridscale.io/objects/servers/{server_uuid}/ips
    

    Response headers

     > HTTP/1.1 202 Accepted
    

    Example response

    null
    

    POST https://api.gridscale.io/objects/servers/{server_uuid}/ips

    You will need the UUID of the IP Address and of the server, which you would like to join the IP Address to.

    Once the IP is linked, you'll receive an empty body, with a 202 response

    You can use this command to DELETE an IP Address linked to a server

    client.Server.removeIp("2d850e53-75e4-4c5c-954b-2757ec46315e", "x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##"
         -H "X-Auth-Token: ##API-Token##"
         -X DELETE \
         https://api.gridscale.io/objects/servers/{server_uuid}/ips/{ip_uuid}
    

    Example response

      > HTTP/1.1 202 Accepted
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/ips/{ip_uuid}

    Request

    URI Parameter type Description
    server_uuid string The UUID of the server, that relates to the IP you are requesting.
    ip_uuid string The UUID of the IP Address you're requesting.

    Possible responses

    Response code Description
    202 successful, the ip has been unset from this server, but still exists in your account to be used elsewhere.
    400 Bad Request (check your ip_uuid, it may not be connected to this server).
    424 Error, please switch of the server before removing an IP Address.

    Linked Storages Get

    You can use this command to get a list of all the storages attached to a server

    client.Server.storages("2d850e53-75e4-4c5c-954b-2757ec46315e").then(function( res ) {
        console.log(res.result.storage_relations);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/storages
    

    Example response

    {
        "storage_relations": [
            {
                "storage_type": "storage",
                "target": 0,
                "bus": 0,
                "capacity": 10,
                "license_product_no": null,
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "controller": 0,
                "lun": 0,
                "create_time": "2018-02-20T11:51:28Z",
                "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "last_used_template": "ec4ef18f-84df-42bb-b7c4-c2957635ee53",
                "bootdevice": false,
                "object_name": "test Storage"
            }, "...": {
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/storages

    Response

    Parameter type Description
    capacity string The capacity of a storage/ISO-Image/template/snapshot in GB.
    object_name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    object_uuid boolean The UUID of an object is always unique, and refers to a specific object.
    bus string The SCSI bus id. The SCSI defines transmission routes like Serial Attached SCSI (SAS), Fibre Channel and iSCSI. Each SCSI device is addressed via a specific number. Each SCSI bus can have multiple SCSI devices connected to it.
    bootdevice boolean Defines if this object is the bootdevice. Storages, Networks and ISO-Images can have a bootdevice configured, but only one bootdevice per Storage, Network or ISO-Image. The boot order is as follows => Network > ISO-Image > Storage.
    server_uuid string The same as the object_uuid
    target string Defines the SCSI target ID. The SCSI defines transmission routes like Serial Attached SCSI (SAS), Fibre Channel and iSCSI. The target ID is a device (e.g. disk).
    storage_type string Indicates the speed of the storage. This may be "storage", "storage_high" or "storage_insane".
    last_used_template string Indicates the UUID of the last used template on this storage (inherited from snapshots).
    create_time datetime The date and time the object was initially created.
    controller string Defines the SCSI controller id. The SCSI defines transmission routes such as Serial Attached SCSI (SAS), Fibre Channel and iSCSI.
    lun integer Is the common SCSI abbreviation of the Logical Unit Number. A lun is a unique identifier for a single disk or a composite of disks.

    Linked Storage Get

    You can use this command to get a list of all the storages attached to a server

    client.Server.storage("2d850e53-75e4-4c5c-954b-2757ec46315e", "006478a5-a79c-4583-9085-d24bb6902fc6").then(function( res ) {
        console.log(res.result.storage_relation);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/storages/{storage_uuid}
    

    Example response

    {
        "storage_relation": {
            "lun": 0,
            "bus": 0,
            "last_used_template": null,
            "bootdevice": true,
            "storage_type": "storage",
            "controller": 0,
            "target": 0,
            "license_product_no": null,
            "object_name": "test",
            "capacity": 10,
            "create_time": "2018-03-12T13:00:40Z",
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
        }
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/storages/{storage_uuid}

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    object_name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    bootdevice boolean Defines if this object is the bootdevice. Storages, Networks and ISO-Images can have a bootdevice configured, but only one bootdevice per Storage, Network or ISO-Image. The boot order is as follows => Network > ISO-Image > Storage.
    create_time datetime` Defines the date and time the object was initially created.
    controller integer Defines the SCSI controller id. The SCSI defines transmission routes such as Serial Attached SCSI (SAS), Fibre Channel and iSCSI.
    bus integer Defines the SCSI bus id. The SCSI defines transmission routes like Serial Attached SCSI (SAS), Fibre Channel and iSCSI. Each SCSI device is addressed via a specific number. Each SCSI bus can have multiple SCSI devices connected to it.
    target integer Defines the SCSI target ID. The SCSI defines transmission routes like Serial Attached SCSI (SAS), Fibre Channel and iSCSI. The target ID is a device (e.g. disk).
    lun integer - maximum: 255 The common SCSI abbreviation of the Logical Unit Number. A lun is a unique identifier for a single disk or a composite of disks.
    last_used_template string Indicates the UUID of the last used template on this storage (inherited from snapshots).
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    storage_type string Indicates the speed of the storage. This may be "storage", "storage_high" or "storage_insane".
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details)

    Linked Storage Patch

    You can use this command to update a Storage linked to a server

    client.Server.patchStorage("2d850e53-75e4-4c5c-954b-2757ec46315e", "006478a5-a79c-4583-9085-d24bb6902fc6", {ordering: 2, bootdevice: true, l3security: null}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"ordering": 2, "bootdevice": true, "l3security": null}' \
         -X PATCH \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}
    

    Request Body

    {
        "bootdevice": true
    }
    

    Example header response

    < HTTP/1.1 202 Accepted
    

    Example body response

    null
    

    PATCH https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}

    Request

    Parameter type required Description
    server_uuid string required The UUID of the server, that relates to the ISO Image you are requesting.
    network_uuid string required The UUID of the ISO Image you're requesting.
    ordering integer The ordering of the network interfaces. Lower numbers have lower PCI-IDs.
    bootdevice boolean Whether the server boots from this network or not.
    l3security string Defines information about IP prefix spoof protection (it allows source traffic only from the IPv4/IPv4 network prefixes). If empty, it allow no IPv4/IPv6 source traffic. If set to null, l3security is disabled (default).

    Possible responses

    Response code Description
    202 successful, the storage has been updated
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The storage does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Response

    Once the storage is updated, you'll receive an empty body, with a 202 response

    You can use this command to link a storage to a server.

    client.Server.addStorage("2d850e53-75e4-4c5c-954b-2757ec46315e", "006478a5-a79c-4583-9085-d24bb6902fc6").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x", "bootdevice": true}' \
         -X POST \
         https://api.gridscale.io/objects/servers/{server_uuid}/storages
    

    Example request body

    {
        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
        "bootdevice" : true
    }
    

    Response headers

     > HTTP/1.1 202 Accepted
    

    Example response

    null
    

    POST https://api.gridscale.io/objects/servers/{server_uuid}/storages

    Request

    Once the storage is linked, you'll receive an empty body, with a 202 response

    parameter type required Description
    object_uuid string required The UUID of the storage you are requesting
    bootdevice Whether the server will boot from this storage device or not.

    You can use this command to DELETE a storage linked to a server

    client.Server.removeStorage("2d850e53-75e4-4c5c-954b-2757ec46315e", "006478a5-a79c-4583-9085-d24bb6902fc6").then(function( res ) {
        console.log(res.success); // if successful => success
        console.log(res.response.statusCode); // if successful => 202
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/servers/{server_uuid}/storages/{storage_uuid}
    

    Example response

      > HTTP/1.1 202 Accepted
    

    DELETE https://api.gridscale.io/objects/servers/{server_uuid}/storages/{storage_uuid}

    Request

    URI Parameter type required Description
    server_uuid string required The UUID of the server, that relates to the Storage you are removing.
    storage_uuid string required The UUID of the Storage you are removing.

    Possible responses

    Response code Description
    202 successful, the storage has been unset from this server, but still exists in your account to be used elsewhere.
    404 The storage does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Linked Networks Get

    You can use this command to get a list of all the networks linked to a server

    client.Server.networks("2d850e53-75e4-4c5c-954b-2757ec46315e").then(function( res ) {
        console.log(res.result.network_relations);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##"
         -H "X-Auth-Token: ##API-Token##"
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks
    

    Example response

    {
        "network_relations": [
            {
                "network_type": "network",
                "l3security": [],
                "mcast": null,
                "bootdevice": true,
                "network_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "l2security": true,
                "vlan": null,
                "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "mac": "1x:12:xx:12:12:12",
                "ordering": 0,
                "firewall": null,
                "firewall_template_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "object_name": "Public Network",
                "partner_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "create_time": "2018-03-12T10:25:12Z",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "public_net": true,
                "vxlan": null
            }, "...": {
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/networks

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    object_name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    bootdevice boolean Defines if this object is the bootdevice. Storages, Networks and ISO-Images can have a bootdevice configured, but only one bootdevice per Storage, Network or ISO-Image. The boot order is as follows => Network > ISO-Image > Storage.
    create_time: datetime Defines the date and time the object was initially created.
    mac string network_mac defines the MAC address of the network interface.
    ordering integer Defines the ordering of the network interfaces. Lower numbers have lower PCI-IDs.
    public_net boolean True if the network is public. If private it will be false. Each private network is a secure and fully transparent 2-Layer network between servers. There is no limit on how many servers can be connected to the same private network.
    l3security string Defines information about IP prefix spoof protection (it allows source traffic only from the IPv4/IPv4 network prefixes). If empty, it allow no IPv4/IPv6 source traffic. If set to null, l3security is disabled (default).
    mpls boolean Is the network a mpls interface.

    Linked Network Get

    You can use this command to get an a network linked to a server

    client.Server.network("2d850e53-75e4-4c5c-954b-2757ec46315e", "d50f3c50-3cf9-44bf-9dff-956a7d72cf4c").then(function( res ) {
        console.log(res.result.network_relation);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##"
         -H "X-Auth-Token: ##API-Token##"
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}
    

    Example response

    {
        "network_relation": {
            "bootdevice": false,
            "firewall_template_uuid": null,
            "object_name": "Public Network",
            "network_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "firewall": null,
            "network_type": "network",
            "ordering": 0,
            "l3security": [
                "123.123.12.1/32",
                "1x12:1234:1:1::123/128"
            ],
            "create_time": "2018-03-12T11:05:28Z",
            "mcast": null,
            "partner_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "mac": "1x:12:xx:12:12:12",
            "vlan": null,
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "public_net": true,
            "l2security": true,
            "vxlan": null
        }
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}

    Request

    Parameter type required Description
    server_uuid string required The UUID of the server, that relates to the ISO Image you are requesting.
    network_uuid string required The UUID of the network you're requesting.

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    object_name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    bootdevice boolean Defines if this object is the bootdevice. Storages, Networks and ISO-Images can have a bootdevice configured, but only one bootdevice per Storage, Network or ISO-Image. The boot order is as follows => Network > ISO-Image > Storage.
    create_time: datetime Defines the date and time the object was initially created.
    mac string network_mac defines the MAC address of the network interface.
    ordering integer Defines the ordering of the network interfaces. Lower numbers have lower PCI-IDs.
    public_net boolean True if the network is public. If private it will be false. Each private network is a secure and fully transparent 2-Layer network between servers. There is no limit on how many servers can be connected to the same private network.
    l3security string Defines information about IP prefix spoof protection (it allows source traffic only from the IPv4/IPv4 network prefixes). If empty, it allow no IPv4/IPv6 source traffic. If set to null, l3security is disabled (default).
    mpls boolean Is the network a mpls interface.

    Linked Network Patch

    You can use this command to get an IP Address linked to a server

    client.Server.patchNetwork("2d850e53-75e4-4c5c-954b-2757ec46315e", "d50f3c50-3cf9-44bf-9dff-956a7d72cf4c", {"ordering": 2, "bootdevice": true, "l3security": null}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"ordering": 2, "bootdevice": true, "l3security": null}' \
         -X PATCH \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}
    

    Request Body

    {
        "ordering": 2,
        "bootdevice": true,
        "l3security": null
    }
    

    Example header response

    < HTTP/1.1 202 Accepted
    

    Example body response

    null
    

    PATCH https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}

    Request

    URI Parameter type required Description
    server_uuid string required The UUID of the server, that relates to the ISO Image you are requesting.
    network_uuid string required The UUID of the ISO Image you're requesting.
    ordering integer The ordering of the network interfaces. Lower numbers have lower PCI-IDs.
    bootdevice boolean Whether the server boots from this network or not.
    l3security string Defines information about IP prefix spoof protection (it allows source traffic only from the IPv4/IPv4 network prefixes). If empty, it allow no IPv4/IPv6 source traffic. If set to null, l3security is disabled (default).

    Possible responses

    Response code Description
    202 successful, the network has been updated
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The network does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Response

    Once the network is updated, you'll receive an empty body, with a 202 response

    You can use this command to link a network to a server.

    client.Server.addNetwork("2d850e53-75e4-4c5c-954b-2757ec46315e", "d50f3c50-3cf9-44bf-9dff-956a7d72cf4c").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"}' \
         -X POST \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks
    

    Response headers

     > HTTP/1.1 202 Accepted
    

    Example response

    null
    

    POST https://api.gridscale.io/objects/servers/{server_uuid}/networks

    Request

    The object_uuid of the network you are requesting can be found in your expert panel.

    Once the network is linked, you'll receive an empty body, with a 202 response

    You can use this command to DELETE a network linked to a server

    client.Server.removeNetwork("2d850e53-75e4-4c5c-954b-2757ec46315e", "d50f3c50-3cf9-44bf-9dff-956a7d72cf4c").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}
    

    Example response

      > HTTP/1.1 202 Accepted
    

    DELETE https://api.gridscale.io/objects/servers/{server_uuid}/isoiamges/{object_uuid}

    Request

    Parameter type required Description
    server_uuid string required The UUID of the server, that relates to the IP you are requesting.
    network_uuid string required The UUID of the IP Address you're requesting.

    Possible responses

    Response code Description
    202 successful, the network has been unset from this server, but still exists in your account to be used elsewhere.
    404 The network does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Linked ISO-Images Get

    You can use this command to get a list of all the IP Addresses linked to a server

    client.Server.isoimages("2d850e53-75e4-4c5c-954b-2757ec46315e").then(function( res ) {
        console.log(res.result.isoimage_relations);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/isoimages
    

    Example response

    {
        "isoimage_relations": [
            {
                "object_name": "Ubuntu 16.04.03 LTS",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "bootdevice": false,
                "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "private": false,
                "create_time": "2018-03-12T09:01:01Z"
            }, "...": {
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/isoimages

    Response

    Parameter type Description
    object_name string The human name of the iso image.
    object_uuid string The machine readable ID of the iso image.
    bootdevice boolean Whether the server boots from this iso image or not.
    server_uuid string The UUID of the server that holds this iso image.
    private boolean Whether the ISO-Image is private or not.
    create_time string Defines the date and time the object was initially created.

    Linked ISO-Image Get

    You can use this command to get an ISO-Image linked to a server

    client.Server.isoimage("2d850e53-75e4-4c5c-954b-2757ec46315e", "8daa0136-3840-4870-a3e6-03d9d5456823").then(function( res ) {
        console.log(res.result.isoimage_relation);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/servers/{server_uuid}/isoimages/{object_uuid}
    

    Example response

    {
        "isoimage_relation": {
            "bootdevice": false,
            "object_name": "Ubuntu 16.04.03 LTS",
            "create_time": "2018-03-12T09:01:01Z",
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
        }
    }
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/isoimages/{object_uuid}

    Request

    Parameter type required Description
    server_uuid string required The UUID of the server, that relates to the ISO Image you are requesting.
    object_uuid string required The UUID of the ISO-Image you're requesting.

    Response

    Parameter type Description
    object_name string The human name of the iso image.
    object_uuid string The machine readable ID of the iso image.
    bootdevice boolean Whether the server boots from this iso image or not.
    create_time string Defines the date and time the object was initially created.

    Linked ISO-Image Patch

    You can use this command to update an ISO-Image linked to a server

    client.Server.patchIsoimage("2d850e53-75e4-4c5c-954b-2757ec46315e", "8daa0136-3840-4870-a3e6-03d9d5456823", {bootdevice: true, name: "Ubunto 14.04"}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"bootdevice": true, "name": "Ubunto 14.04"}' \
         -X PATCH \
         https://api.gridscale.io/objects/servers/{server_uuid}/isoimages/{object_uuid}
    

    Example header response

    < HTTP/1.1 202 Accepted
    

    Example body response

    null
    

    PATCH https://api.gridscale.io/objects/servers/{server_uuid}/isoimages/{object_uuid}

    Request

    Parameter type required Description
    server_uuid string required The UUID of the server, that relates to the ISO Image you are requesting.
    object_uuid string required The UUID of the ISO-Image you're requesting.

    Possible responses

    Response code Description
    202 successful, the ip has been unset from this server, but still exists in your account to be used elsewhere.
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The ISO Image does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Response

    Once the ISO Images is linked, you'll receive an empty body, with a 202 response

    You can use this command to link an ISO-Image to a server.

    client.Server.addIsoimage("2d850e53-75e4-4c5c-954b-2757ec46315e", "8daa0136-3840-4870-a3e6-03d9d5456823").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"}' \
         -X POST \
         https://api.gridscale.io/objects/servers/{server_uuid}/isoimages
    

    Response headers

     > HTTP/1.1 202 Accepted
    

    Example response

    null
    

    POST https://api.gridscale.io/objects/servers/{server_uuid}/isoimages

    Once the Iso-Images is linked, you'll receive an empty body, with a 202 response

    You can use this command to remove an ISO-Image linked to a server

    client.Server.removeIsoimage("2d850e53-75e4-4c5c-954b-2757ec46315e", "8daa0136-3840-4870-a3e6-03d9d5456823").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/servers/{server_uuid}/isoimages/{object_uuid}
    

    Example response

      > HTTP/1.1 202 Accepted
    

    GET https://api.gridscale.io/objects/servers/{server_uuid}/isoiamges/{object_uuid}

    Request

    Parameter type Description
    server_uuid string The UUID of the server, that relates to the IP you are requesting.
    object_uuid string The UUID of the ISO-Image you're requesting.

    Possible responses

    Response code Description
    202 successful, the ip has been unset from this server, but still exists in your account to be used elsewhere.
    404 The ISO Image does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Storages

    SSD Cloud Storage

    Choose between 3 different performance speeds to meet even the highest I/O-requirements. All your data is encrypted and stored on enterprise-grade SSDs in three different availability zones. Our storage technology is designed for security, availability and speed. We keep all your data on at least three independent storage nodes in different availability zones. This will protect your data from loss and corruption.

    In this section we will show you how to get started creating your own storage, after getting your storage setup, head over to the server-storage relation section - here - to link it to a server.

    Storages Get

    You can use this command to get a list of all storages

    client.Storage.list().then(function( res ) {
        console.log(res.result.storages);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/storages
    

    Example Response

    {
        "storages": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "change_time": "2018-03-13T09:24:23Z",
                "location_iata": "fra",
                "status": "active",
                "license_product_no": null,
                "location_country": "de",
                "usage_in_minutes": 770,
                "last_used_template": null,
                "current_price": 0.003388,
                "capacity": 10,
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "storage_type": "storage",
                "parent_uuid": null,
                "name": "test Storage",
                "location_name": "de/fra",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "snapshots": [],
                "relations": {
                    "servers": [
                        {
                            "bootdevice": true,
                            "target": 0,
                            "controller": 0,
                            "bus": 0,
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "lun": 0,
                            "create_time": "2018-03-13T09:24:25Z",
                            "object_name": "tes"
                        }
                    ],
                    "snapshot_schedules": []
                },
                "labels": [],
                "create_time": "2018-03-13T09:24:23Z"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/storages

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    storage_type (one of storage, storage_high, storage_insane)
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details).
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    labels array List of labels.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array Objects related to this Storage

    Storage Create

    You can use this command to create a Storage

    client.Storage.list().then(function( res ) {
        console.log(res.result.storages);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "test","location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950","capacity": 10}' \
         -X POST \
         https://api.gridscale.io/objects/storages
    

    Example Request Body

    {
        "name": "test",
        "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
        "capacity": 10
    }
    

    Example Response

    {
        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
        "request_uuid": "07d8aaae-97a0-4444-b7d3-0fc3acb068fe"
    }
    

    POST https://api.gridscale.io/objects/storages

    Request

    A list of possible parameters for your POST request.

    Parameter type required Description
    name string required The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    capacity int required required (integer - minimum: 1 - maximum: 4096)
    template object An object holding important values such as hostnames, passwords, and SSH keys.
    hostname string Hostname to set for the installed storage. The running server will use this as its hostname. Valid only for public Linux and Windows templates.
    template_uuid string The UUID of a template (public or private).
    password string The root (Linux) or Administrator (Windows) password to set for the installed storage. Valid only for public templates. The password has to be either plaintext or a crypt string (modular crypt format - MCF)..
    password_type string (one of plain, crypt)
    sshkeys string (array of any - minItems: 0)
    labels array List of labels.
    location_uuid string required Helps to identify which datacenter an object belongs to.
    storage_type string (one of storage, storage_high, storage_insane)

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    request_uuid string The UUID of the successful request.

    Storage Get

    You can use this request to get information regarding a specific storage

    client.Storage.get("e7f6cb47-4948-45cc-83de-b7bd08ddf9ec").then(function( res ) {
        console.log(res.result.storage);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/storages/{storage_uuid}
    

    Example Response

    {
        "storage": {
            "parent_uuid": null,
            "labels": [],
            "snapshots": [],
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "relations": {
                "servers": [],
                "snapshot_schedules": []
            },
            "name": "test",
            "status": "active",
            "location_country": "de",
            "usage_in_minutes": 370,
            "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
            "change_time": "2018-03-13T12:09:12Z",
            "storage_type": "storage",
            "license_product_no": null,
            "current_price": 0.001628,
            "create_time": "2018-03-13T12:09:12Z",
            "last_used_template": null,
            "capacity": 10,
            "location_name": "de/fra",
            "location_iata": "fra"
        }
    }
    

    GET https://api.gridscale.io/objects/storages/{storage_uuid}

    Resonse

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    storage_type (one of storage, storage_high, storage_insane)
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details).
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    labels array List of labels.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name: (string - minLength: 1 - maxLength: 64) The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country: (string) Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata: (string) Uses IATA airport code, which works as a location identifier.
    relations: (array of object) Objects related to this Storage

    Storage Patch

    You can use this command to Update a Storage

    client.Storage.patch("e7f6cb47-4948-45cc-83de-b7bd08ddf9ec", {"name": "test","capacity": 10, "labels": ["backup"]}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "test","capacity": 10, "labels": ["backup"]}' \
         -X PATCH \
         https://api.gridscale.io/objects/storages/{storage_uuid}
    

    Example request body

    {
      "name": "test",
      "capacity": 10,
       "labels": [
         "backup"
       ]
    }
    

    Response

    If the update was successful, you will receive a 202 successful header response, with a body of null. You can preview the changes with a GET request to the same endpoint.

    Example header response

    < HTTP/1.1 202 Accepted
    

    Example reponse

    null
    

    PATCH https://api.gridscale.io/objects/storages/{storage_uuid}

    Storage Delete

    You can use this command to Delete a Storage

    client.Storage.remove("006478a5-a79c-4583-9085-d24bb6902fc6").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/storages/{storage_uuid}
    

    Example response

    > HTTP/1.1 204 No Content
    

    DELETE https://api.gridscale.io/objects/storages/{storage_uuid}

    Response

    Once a storage is deleted, you will receive a 204 header response as confirmation.

    Possible responses

    Response code Description
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The Storage does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Storage Events

    You can use this command to get a list of all storages

    client.Storage.events("e7f6cb47-4948-45cc-83de-b7bd08ddf9ec").then(function( res ) {
        console.log(res.result).events;
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/storages/{storage_uuid}/events
    

    Example Response

    {
        "events": [
            {
                "change": "Create new storage test with 10 GiB capacity",
                "request_type": "storage_add",
                "object_type": "storage",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "request_uuid": "a25bfc91-37c4-45a9-8876-b3bc28661f5d",
                "timestamp": "2018-03-13T13:49:28Z",
                "activity": "add",
                "request_status": "done",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/storages/{storage_uuid}/events

    Response

    Parameter type Description
    create_time datetime The date and time when the request was received.
    user_uuid string The UUID of the User who triggered the request.
    object_type string Object type of the event that was triggered for (e.g. storage, server, ...).
    object_uuid string The object that was changed during the request.
    activity string The operation that was used on the object (e.g. update, remove, ...).
    change string What has been changed on the object.

    Networks

    Our high performance Juniper core switching infrastructure gives you unlimited freedom with your network.

    We are one of the few providers that allow complete flexibility when interconnecting network components. You can build complex firewall rules, create as many private networks as you like and connect your servers through multiple networks.

    Each private network is assigned a unique encryption key which encrypts all your data. Keeping your data save and sound, even between two data centers. We have direct connections to all major upstream providers, including the world's largest internet exchanges (AMSIX, DECIX to name a few).

    In this section we will show you how to get started creating your own network, after getting your network setup, head over to the server-network relation section - here - to link it to a server.

    Networks Get

    You can use this command to get a list of all networks

    client.Network.list().then(function( res ) {
        console.log(res.result.networks);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/networks
    

    Example Response

    {
        "networks": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "change_time": "2018-03-13T09:24:23Z",
                "location_iata": "fra",
                "status": "active",
                "license_product_no": null,
                "location_country": "de",
                "usage_in_minutes": 770,
                "last_used_template": null,
                "current_price": 0.003388,
                "capacity": 10,
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "network_type": "network",
                "parent_uuid": null,
                "name": "test Network",
                "location_name": "de/fra",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "snapshots": [],
                "relations": {
                    "servers": [
                        {
                            "bootdevice": true,
                            "target": 0,
                            "controller": 0,
                            "bus": 0,
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "lun": 0,
                            "create_time": "2018-03-13T09:24:25Z",
                            "object_name": "tes"
                        }
                    ],
                    "snapshot_schedules": []
                },
                "labels": [],
                "create_time": "2018-03-13T09:24:23Z"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/networks

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    network_type (one of network, network_high, network_insane)
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details).
    capacity integer The capacity of a network/ISO-Image/template/snapshot in GB.
    labels array List of labels.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array Objects related to this Network

    Network Create

    You can use this command to create a new Network

    client.Network.create({"name": "test","location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950","l2security": true}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "test","location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950","l2security": true}' \
         -X POST \
         https://api.gridscale.io/objects/networks
    

    Example Request Body

    {
        "name": "test",
        "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
        "l2security": true
    }
    

    Example Response

    {
        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
        "request_uuid": "07d8aaae-97a0-4444-b7d3-0fc3acb068fe"
    }
    

    POST https://api.gridscale.io/objects/networks

    Request

    A list of possible parameters for your POST request.

    Parameter type Description
    name string request The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    location_uuid string required Helps to identify which datacenter an object belongs to.
    l2security boolean Defines information about MAC spoofing protection (filters layer2 and ARP traffic based on MAC source). It can only be (de-)activated on a private network - the public network always has l2security enabled. It will be true if the network is public, and false if the network is private.

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    request_uuid string The UUID of the successful request.

    Network Get

    You can use this request to get information regarding a specific network

    client.Network.get("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.result.network);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/networks
    

    Example Response

    {
        "network": {
            "location_country": "de",
            "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
            "public_net": false,
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "network_type": "network",
            "name": "test",
            "delete_block": false,
            "status": "active",
            "create_time": "2018-03-14T08:04:16Z",
            "l2security": false,
            "relations": {
                "vlans": [],
                "servers": []
            },
            "labels": [],
            "change_time": "2018-03-14T08:04:16Z",
            "location_iata": "fra",
            "location_name": "de/fra"
        }
    }
    

    GET https://api.gridscale.io/objects/networks

    Resonse

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    network_type (one of network, network_high, network_insane)
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details).
    capacity integer The capacity of a network/ISO-Image/template/snapshot in GB.
    labels array List of labels.
    status status indicates the status of the object.
    create_time datetime The date and time the object was initially created.
    change_time datetime The date and time of the last object change.
    current_price number The price for the current period since the last bill.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array Objects related to this Network

    Network Patch

    You can use this command to Update a Network

    client.Network.patch("x123xx1x-123x-1x12-123x-123xxx123x1x", {name: "new_name",l2security: false}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "new_name","l2security": false}' \
         -X PATCH \
         https://api.gridscale.io/objects/networks/{network_uuid}
    

    Example request body

    {
      "name": "new_name",
      "l2security": false
    }
    

    Example header response

    < HTTP/1.1 204 Accepted
    

    PATCH https://api.gridscale.io/objects/networks/{network_uuid}

    Response

    If the update was successful, you will receive a 204 successful header response, and an empty body. You can preview the changes with a GET request to the same endpoint.

    Network Delete

    You can use this command to Delete a Network

    client.Network.remove("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/networks/{network_uuid}
    

    Example response

    > HTTP/1.1 204 No Content
    

    DELETE https://api.gridscale.io/objects/networks/{network_uuid}

    Response

    Once a network is deleted, you will receive a 204 header response as confirmation.

    Possible responses

    Response code Description
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The Network does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Network Events

    You can use this command to get a list of all networks

    client.Network.events("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/networks/{network_uuid}/events
    

    Example Response`

    {
        "events": [
            {
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "request_uuid": "f83d74d1-53cb-462b-82b1-db87ab77ce67",
                "object_type": "network",
                "change": "Update network Public Network with: name=Public Network test",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "timestamp": "2018-03-14T08:40:32Z",
                "request_status": "done",
                "request_type": "network_update",
                "activity": "update"
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/networks/{network_uuid}/events

    Response

    Parameter type Description
    timestamp datetime The date and time when the request was received.
    user_uuid string The UUID of the User who triggered the request.
    request_uuid string The UUID of the request of the change.
    request_status string Status of the request (e.g. failed, done, ...)
    request_type string Further explanation of the update, network_update in this case, could be network_delete etc.
    object_type string Object type of the event that was triggered for (e.g. network, server, ...).
    object_uuid string The object that was changed during the request.
    activity string The operation that was used on the object (e.g. update, remove, ...).
    change string Human readable description of what was changed on the object.

    IP Addresses

    We are one of the first cloud providers that fully supports IPv6. We strongly believe that IPv6 is the Internet Protocol of the future. For this reason all modules and components at gridscale are 100% IPv6 compatible.

    Failover-IPs are one of the most complex features in a network layer. With gridscale no API requests or other workarounds are required to move IPs between servers - simply use the operating system tools of your choice. Use standard tools like 'keepalived', 'pacemaker', etc. to make your servers highly available.

    IP Addresses represent a publicly-accessible static IP Addresses that can be mapped to one of your Servers. They can be used to create highly available infrastructures or link a simple server to the public. Floating IPs are bound to a specific location.

    In this section we will show you how to get started creating your own IP, after getting your IP setup, head over to the server-IP relation section - here - to link it to a server.

    IPs Get

    You can use this command to get a list of all IPs

    client.IP.list().then(function( res ) {
        console.log(res.result.ips);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/ips
    

    Example Response

    {
        "ips": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "create_time": "2018-02-01T13:48:13Z",
                "status": "active",
                "relations": {
                    "loadbalancers": [],
                    "servers": [
                        {
                            "create_time": "2018-02-20T11:51:18Z",
                            "server_name": "server with a new name2",
                            "server_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
                        }
                    ]
                },
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_country": "de",
                "prefix": "123.123.12.1/128"
                "delete_block": false,
                "failover": false,
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "location_name": "de/fra",
                "labels": [],
                "change_time": "2018-02-01T13:48:13Z",
                "ip": "123.123.12.1",
                "family": 6,
                "location_iata": "fra",
                "reverse_dns": "static-123-123-123-123.ipv6.exampleserver.com",
                "current_price": 0.0,
                "usage_in_minutes": 0,
                "name": "Default IP"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/ips

    Response

    Parameter type Description
    ip string Defines the IP Address (v4 or v6).
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    family The IP Address family (v4 or v6).
    failover boolean Sets failover mode for this IP. If true, then this IP is no longer available for DHCP and can no longer be related to any server.
    reverse_dns string Defines the reverse DNS entry for the IP Address (PTR Resource Record).
    current_price number Defines the price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array List of servers related to this IP Address.
    delete_block boolean Defines if the object is administratively blocked. If true, it can not be deleted by the user.

    IP Create

    You can use this command to create a new IP

    client.IP.create({"family": 4,"location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950","failover": true}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d  '{"family": 4,"location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950","failover": true}' \
         -X POST \
         https://api.gridscale.io/objects/ips
    

    Example Request Body

    {
     "family": 4,
     "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
     "failover": true
    }
    

    Example Response

    {
        "request_uuid": "8e9a4818-d145-4aa3-918a-60cc32b37e96",
        "ip": "123.123.12.1",
        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
        "prefix": "123.123.12.1/32"
    }
    

    POST https://api.gridscale.io/objects/ips

    Request

    A list of possible parameters for your POST request.

    Parameter type required Description
    family integer required Defines the IP Address family (v4 or v6).
    location_uuid string required Helps to identify which datacenter an object belongs to.
    failover boolean Sets failover mode for this IP. If true, then this IP is no longer available for DHCP and can no longer be related to any server.
    reverse_dns string Defines the reverse DNS entry for the IP Address (PTR Resource Record).
    labels array List of labels.

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    prefix string ip_prefix defines the IP prefix.
    ip string ip_address defines the IP Address (v4 or v6).

    IP Get

    You can use this request to get information regarding a specific network

    client.IP.get("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.result.ip);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/ips/{ip_uuid}
    

    Example Response

    {
        "network": {
            "location_country": "de",
            "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
            "public_net": false,
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "network_type": "network",
            "name": "test",
            "delete_block": false,
            "status": "active",
            "create_time": "2018-03-14T08:04:16Z",
            "l2security": false,
            "relations": {
                "vlans": [],
                "servers": []
            },
            "labels": [],
            "change_time": "2018-03-14T08:04:16Z",
            "location_iata": "fra",
            "location_name": "de/fra"
        }
    }
    

    GET https://api.gridscale.io/objects/ips/{ip_uuid}

    Resonse

    Parameter type Description
    ip string ip_address defines the IP Address (v4 or v6).
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    family integer Defines the IP Address family (v4 or v6).
    failover boolean Sets failover mode for this IP. If true, then this IP is no longer available for DHCP and can no longer be related to any server.
    reverse_dns string Defines the reverse DNS entry for the IP Address (PTR Resource Record).
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations List of servers related to this IP Address.
    delete_block boolean Defines if the object is administratively blocked. If true, it can not be deleted by the user.

    IP Patch

    You can use this command to Update an IP

    client.IP.patch("x123xx1x-123x-1x12-123x-123xxx123x1x", {"name": "new_name","l2security": false}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "new_name","l2security": false}' \
         -X PATCH \
         https://api.gridscale.io/objects/ips/{ip_uuid}
    

    Example request body

    {
      "name": "new_name",
      "l2security": false
    }
    

    Example header response

    < HTTP/1.1 204 Accepted
    

    PATCH https://api.gridscale.io/objects/ips/{ip_uuid}

    Request

    Parameter type Description
    failover boolean Sets failover mode for this IP. If true, then this IP is no longer available for DHCP and can no longer be related to any server.
    reverse_dns string Defines the reverse DNS entry for the IP Address (PTR Resource Record).
    labels array List of labels.

    Response

    If the update was successful, you will receive a 204 successful header response. You can preview the changes with a GET request to the same endpoint.

    IP Delete

    You can use this command to Delete an IP

    client.IP.remove("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/ips/{ip_uuid}
    

    Example response

    > HTTP/1.1 204 No Content
    

    DELETE https://api.gridscale.io/objects/ips/{ip_uuid}

    Response

    Once an IP is deleted, you will receive a 204 header response as confirmation.

    Possible responses

    Response code Description
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The IP does not exist.
    424 The current object state does not allow changes - see response body for more information.

    IP Events

    You can use this command to get a list of all the events on an IP Address.

    client.IP.events("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.result.events);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/ips/{ip_uuid}/events
    

    Example Response`

    {
        "events": [
            {
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "request_uuid": "03f1de09-e5de-4d82-aa03-6f82c63d2d64",
                "object_type": "ipaddr",
                "change": "Update IP 123.123.12.1 with: failover=False",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "timestamp": "2018-03-14T11:54:33Z",
                "request_status": "done",
                "request_type": "ipaddr_update",
                "activity": "update"
            },
            {
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "request_uuid": "8e9a4818-d145-4aa3-918a-60cc32b37e96",
                "object_type": "ipaddr",
                "change": "Request new IP 123.123.12.1",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "timestamp": "2018-03-14T11:44:49Z",
                "request_status": "done",
                "request_type": "ipaddr_add",
                "activity": "add"
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/ips/{ip_uuid}/events

    Response

    Parameter type Description
    create_time datetime The date and time when the request was received.
    user_uuid string The UUID of the User who triggered the request.
    object_type string Object type of the event that was triggered for (e.g. storage, server, ...).
    object_uuid string The object that was changed during the request.
    activity string The operation that was used on the object (e.g. update, remove, ...).
    change string What has been changed on the object.

    Firewalls

    Setting up a firewall before giving public access to your servers is crucial to keep your servers secure.

    We have an extensive list of pre-designed templates, but if you need a more custom firewall we will show you how to set one up via the API and place it between a Network and Server.

    Firewalls Get

    You can use this command to get a list of all your firewall templates

    client.Firewall.list().then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/firewalls
    

    example response

    "9a3fdd6e-fc2c-43a3-a8ac-6ec06898f9ce": {
    "status": "active",
    "labels": [],
    "object_uuid": "9a3fdd6e-fc2c-43a3-a8ac-6ec06898f9ce",
    "change_time": "2017-10-18T10:05:15Z",
    "rules": {
        "rules-v6-in": [
            {
                "order": 0,
                "protocol": "tcp",
                "action": "accept",
                "dst_port": "22"
            },
        ],
        "rules-v4-in": [
            {
                "order": 0,
                "protocol": "tcp",
                "action": "accept",
                "dst_port": "22"
            },
        ],
        "rules-v4-out": [],
        "rules-v6-out": []
    },
    "create_time": "2017-10-17T12:38:42Z",
    "private": false,
    "relations": {
        "networks": []
    },
    "name": "Webserver + SSH"
    },
    

    GET https://api.gridscale.io/objects/firewalls

    Possible Header Responses

    status code Description
    404 Firewall not found
    401 No firewalls to return
    204 X-Auth-UserId or X-Auth-Token not set
    200 OK

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    create_time datetime The time the firewall was created,
    labels array List of labels that identify this firewall.
    relations.networks array The networks currently using this firewall.
    rules.rules-v4-in Firewall template rules for inbound traffic for ipv4 addresses
    rules.rules v4-out Firewall template rules for outbound traffic for ipv4 addresses
    rules.rules-v6-in Firewall template rules for inbound traffic for ipv6 addresses
    rules.rules-v6-out Firewall template tules for outbounf traffic for ipv6 addresses
    private If this is a private or public Firewall-Template

    Rules

    Parameter type Description
    order The order at which the firewall will compare packets against it's rules, a packet will be compared against the first rule, it will either allow it to pass or block it and it won't be matched against any other rules. However, if it does no match the rule, then it will proceed onto rule 2. Packets that do not match any rules are blocked by default.
    protocol Either udp or tcp
    src_cidr Either an IPv4/6 address or and IP Network in CIDR format. If this field is empty then all IPs have access to this service.
    action This defines what the firewall will do. Either accept or drop.
    dst_port int a Number between 1 and 65535, port ranges are seperated by a colon for FTP

    Firewall Get

    You can use this command to get information of a firewall template

    client.Firewall.get(firewall_uuid).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/firewalls/{firewall_uuid}
    

    example response

    "status": "active",
    "labels": [],
    "object_uuid": "9a3fdd6e-fc2c-43a3-a8ac-6ec06898f9ce",
    "change_time": "2017-10-18T10:05:15Z",
    "rules": {
        "rules-v6-in": [
            {
                "order": 0,
                "protocol": "tcp",
                "action": "accept",
                "dst_port": "22"
            },
        ],
        "rules-v4-in": [
            {
                "order": 0,
                "protocol": "tcp",
                "action": "accept",
                "dst_port": "22"
            },
        ],
        "rules-v4-out": [],
        "rules-v6-out": []
    },
    "create_time": "2017-10-17T12:38:42Z",
    "private": false,
    "relations": {
        "networks": []
    },
    "name": "Webserver + SSH"
    

    GET https://api.gridscale.io/objects/firewalls

    Possible Header Responses

    status code Description
    404 Firewall not found
    401 No firewalls to return
    204 X-Auth-UserId or X-Auth-Token not set
    200 OK

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    create_time datetime The time the firewall was created,
    labels array List of labels that identify this firewall.
    relations.networks array The networks currently using this firewall.
    rules.rules-v4-in Firewall template rules for inbound traffic for ipv4 addresses
    rules.rules v4-out Firewall template rules for outbound traffic for ipv4 addresses
    rules.rules-v6-in Firewall template rules for inbound traffic for ipv6 addresses
    rules.rules-v6-out Firewall template tules for outbounf traffic for ipv6 addresses
    private If this is a private or public Firewall-Template

    Rules

    Parameter type Description
    order The order at which the firewall will compare packets against it's rules, a packet will be compared against the first rule, it will either allow it to pass or block it and it won't be matched against any other rules. However, if it does no match the rule, then it will proceed onto rule 2. Packets that do not match any rules are blocked by default.
    protocol Either udp or tcp
    src_cidr Either an IPv4/6 address or and IP Network in CIDR format. If this field is empty then all IPs have access to this service.
    action This defines what the firewall will do. Either accept or drop.
    dst_port int a Number between 1 and 65535, port ranges are seperated by a colon for FTP

    Firewall Delete

    You can use this code to delete a firewall

    client.Firewall.remove("a2c0a8a7-c9e5-471d-b601-f547fe075eed").then(function( res ) {
        console.log(res);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/firewalls/{firewall_uuid}
    

    To delete a firewall just send a delete request to the /objects/firewalls/{firewall_uuid} endpoint.

    Response

    A successful response will be an empty body and a 204 header response.

    Firewall Create

    You can use this code to remove a firewall

    client.Firewall.create({"name":"test","labels": ["webmail"], "rules": { "rules-v4-in": [{"port": 20, "protocol": "tcp", "order": 0, "action": "accept"}]}}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name":"test","labels": ["webmail"], "rules": { "rules-v4-in": [{"port": 20, "protocol": "tcp", "order": 0, "action": "accept"}]}}' \
         -X POST \
         https://api.gridscale.io/objects/firewalls/
    

    request body

    {
        "name":"test",
        "labels": ["webmail"],
        "rules": {
            "rules-v4-in": [{
                "port": 20,
                 "protocol": "tcp",
                  "order": 0,
                   "action": "accept"
            }]
        }
    }
    

    Example resonse

    { 
      "object_uuid": "1b1f74c2-2925-4039-8a8f-01917629a4f0",
      "request_uuid": "40bd4a0d-e8c3-4eb4-b168-cf9d929c9873" 
    }
    

    Request

    Parameter type Description
    labels array List of labels that identify this firewall.
    rules.rules-v4-in Firewall template rules for inbound traffic for ipv4 addresses
    rules.rules v4-out Firewall template rules for outbound traffic for ipv4 addresses
    rules.rules-v6-in Firewall template rules for inbound traffic for ipv6 addresses
    rules.rules-v6-out Firewall template tules for outbounf traffic for ipv6 addresses
    private If this is a private or public Firewall-Template

    Rules

    Parameter type Description
    order The order at which the firewall will compare packets against it's rules, a packet will be compared against the first rule, it will either allow it to pass or block it and it won't be matched against any other rules. However, if it does no match the rule, then it will proceed onto rule 2. Packets that do not match any rules are blocked by default.
    protocol Either udp or tcp
    src_cidr Either an IPv4/6 address or and IP Network in CIDR format. If this field is empty then all IPs have access to this service.
    action This defines what the firewall will do. Either accept or drop.
    dst_port int a Number between 1 and 65535, port ranges are seperated by a colon for FTP

    Response

    The response will contain the newly created Firewalls object_uuid, which you can further use to relate it between your network and server.

    Firewall Update

    You can use this code to update a firewall

    client.Firewall.patch("14a332b0-67b1-4132-abb5-618dcdd86e6d", {"name": "Updated Name"}).then(function( res ) {
        console.log(res.success); // returns true if successful
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "Updated Name","labels": ["webmail"],"rules": {"rules-v4-in": [{"port": 20,"protocol": "tcp","order": 0,"action": "accept"}],"rules-v6-in": [{"port": 22, "protocol": "tcp","order": 1,"action": "drop"}]}}' \
         -X PATCH \
         https://api.gridscale.io/objects/firewalls/{firewall_uuid}
    

    request body

    {
        "name": "Updated Name",
        "labels": ["webmail"],
        "rules": {
            "rules-v4-in": [{
                "port": 20,
                 "protocol": "tcp",
                  "order": 0,
                   "action": "accept"
            }],
            "rules-v6-in": [{
                "port": 22, 
                "protocol": "tcp",
                "order": 1,
                "action": "drop"
            }]
        }
    }
    

    Request

    Parameter type Description
    labels array List of labels that identify this firewall.
    rules.rules-v4-in Firewall template rules for inbound traffic for ipv4 addresses
    rules.rules v4-out Firewall template rules for outbound traffic for ipv4 addresses
    rules.rules-v6-in Firewall template rules for inbound traffic for ipv6 addresses
    rules.rules-v6-out Firewall template tules for outbounf traffic for ipv6 addresses
    private If this is a private or public Firewall-Template

    Rules

    Parameter type Description
    order The order at which the firewall will compare packets against it's rules, a packet will be compared against the first rule, it will either allow it to pass or block it and it won't be matched against any other rules. However, if it does no match the rule, then it will proceed onto rule 2. Packets that do not match any rules are blocked by default.
    protocol Either udp or tcp
    src_cidr Either an IPv4/6 address or and IP Network in CIDR format. If this field is empty then all IPs have access to this service.
    action This defines what the firewall will do. Either accept or drop.
    dst_port int a Number between 1 and 65535, port ranges are seperated by a colon for FTP

    Response

    A successful response will be an empty body and a 204 header response.

    Firewall Events

    You can use this code to get the events a firewall

    client.Firewall.events("14a332b0-67b1-4132-abb5-618dcdd86e6d").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/firewalls/{firewall_uuid}
    

    Response

    The response body will display all the events for a firewall, such as creation time stamps and any changes made.

    example response

    {
        "events": [
            {
                "activity": "add",
                "user_uuid": "96a2bf78-69e2-4efa-a915-d33a85ebaa7c",
                "timestamp": "2018-04-20T13:09:43Z",
                "request_uuid": "c744e78f-47b0-4edf-8723-581809efadd7",
                "object_uuid": "690d380d-5f46-47be-9729-951fb45f8ef9",
                "change": "Create new firewall test",
                "request_type": "firewall_add",
                "object_type": "firewall",
                "request_status": "done"
            }
        ]
    }
    

    Response

    Parameter type Description
    activity Catagory of the change
    user_uuid The unique uuid of the user that made the change
    timestamp Date and time the change was made
    change Short sentance describing the change
    request_type A keyword describing the event joining the object_type and activity
    object_type The target object of the event.

    you can use this code to link a firewall to a network/server relation

    client.Server.patchNetwork("server_uuid", "network_uuid", {"firewall_template_uuid":"firewall_uuid"}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \ 
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"firewall_template_uuid": "firewall_uuid"}' \
         -X PATCH \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}
    

    request body

    {
        "firewall_template_uuid": "firewall_uuid"
    }
    

    Response

    To link a Firewall to a Network/Server relation, you will need the unique uuid's of the Network, Server and Firewall You must send the server and network uuid as URI paramters, and the firewall uuid in the body as the firewall_template_uuid

    The reponse will be null and a 202 accepted response, signifying success.

    you can use this code to unlink a firewall to a network/server relation

    client.Server.patchNetwork("server_uuid", "network_uuid", { "firewall": null, "firewall_template_uuid": null}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"firewall": null, "firewall_template_uuid": null}' \
         -X PATCH \
         https://api.gridscale.io/objects/servers/{server_uuid}/networks/{network_uuid}
    

    request body

    {
        "firewall_template_uuid": null,
        "firewall": null
    }
    

    Response

    To unlink a Firewall from a Network/Server relation, you will need the unique uuid's of the Network and Server You must send the server and network uuid as URI paramters, and update the firewall and firewall_template_uuid to a value of null

    The reponse will be null and a 202 accepted response, signifying success.

    ISO Images

    When creating a server you need to choose which operating system you would like to use, if we don't natively support the operating system you work with, don't worry, just give it a name, put in the source_url, and you ready to go.

    In this section we will show you how to get started creating your own ISO Images, after getting your ISO Image setup, head over to the server-ISO relation section - here - to link it to a server.

    ISO-Images Get

    You can use this command to get a list of all ISO Images

    client.ISOImage.list().then(function( res ) {
        console.log(res.result.isoimages);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/isoimages
    

    Example Response

    {
        "isoimages": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "relations": {
                    "servers": []
                },
                "description": null,
                "location_name": "de/fra",
                "source_url": "http://de.releases.ubuntu.com/16.04.3/ubuntu-16.04.3-server-amd64.iso",
                "labels": [],
                "location_iata": "fra",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "status": "active",
                "create_time": "2017-10-25T12:39:23Z",
                "name": "Ubuntu 16.04.03 LTS",
                "version": null,
                "location_country": "de",
                "usage_in_minutes": 0,
                "private": false,
                "change_time": "2017-10-26T15:52:34Z",
                "capacity": 1,
                "current_price": 0.0
            }
      }
    }
    

    GET https://api.gridscale.io/objects/isoimages

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    private boolean If the object is private, the value will be true. Otherwise the value will be false.
    version string Upstream version of the ISO-Image release
    description string Description of the ISO-Image release
    source_url string network_source_url contains the source URL of the ISO-Image that it was originally fetched from.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array List of servers related to this ISO-Image

    ISO-Image Create

    You can use this command to create a new ISO Image

    client.ISOImage.create({"name": "test","source_url": "http://releases.ubuntu.com/16.04.4/ubuntu-16.04.4-server-amd64.iso?_ga=2.188975915.108704605.1521033305-403279979.1521033305","location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "test","source_url": "http://releases.ubuntu.com/16.04.4/ubuntu-16.04.4-server-amd64.iso?_ga=2.188975915.108704605.1521033305-403279979.1521033305","location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"}' \
         -X POST \
         https://api.gridscale.io/objects/isoimages
    

    Example Request Body

    {
        "name": "test",
        "source_url": "http://releases.ubuntu.com/16.04.4/ubuntu-16.04.4-server-amd64.iso?_ga=2.188975915.108704605.1521033305-403279979.1521033305",
        "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"
    }
    

    Example Response

    {
        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
        "request_uuid": "bcc3e506-0f0b-4af2-a7d1-4c30f7828529"
    }
    

    POST https://api.gridscale.io/objects/isoimages

    Request

    A list of possible parameters for your POST request.

    Parameter type required Description
    name string required The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    source_url string required network_source_url contains the source URL of the ISO-Image that it was originally fetched from.
    labels array List of labels.
    location_uuid string required Helps to identify which datacenter an object belongs to.

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.

    ISO-Image Get

    You can use this request to get information regarding a specific ISO Image

    client.ISOImage.get("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.result.isoimage);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/isoimages/{isoimage_uuid}
    

    Example Response

    {
        "isoimage": {
            "private": true,
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "location_country": "de",
            "status": "active",
            "name": "test",
            "location_iata": "fra",
            "current_price": 3.52e-05,
            "description": null,
            "relations": {
                "servers": []
            },
            "usage_in_minutes": 8,
            "source_url": "http://releases.ubuntu.com/16.04.4/ubuntu-16.04.4-server-amd64.iso?_ga=2.188975915.108704605.1521033305-403279979.1521033305",
            "capacity": 1,
            "create_time": "2018-03-15T07:08:03Z",
            "labels": [],
            "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
            "version": null,
            "change_time": "2018-03-15T07:08:03Z",
            "location_name": "de/fra"
        }
    }
    

    GET https://api.gridscale.io/objects/isoimages/{isoimage_uuid}

    Resonse

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    private boolean If the object is private, the value will be true. Otherwise the value will be false.
    version string Upstream version of the ISO-Image release
    description string Description of the ISO-Image release
    source_url string network_source_url contains the source URL of the ISO-Image that it was originally fetched from.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array List of servers related to this ISO-Image

    ISO-Image Patch

    You can use this command to Update an ISO Image

    client.ISOImage.patch("x123xx1x-123x-1x12-123x-123xxx123x1x", {"name": "new_name"}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "new_name"}' \
         -X PATCH \
         https://api.gridscale.io/objects/isoimages/{isoimage_uuid}
    

    Example request body

    {
      "name": "new_name",
    }
    

    Example header response

    < HTTP/1.1 204 Accepted
    

    PATCH https://api.gridscale.io/objects/isoimages/{isoimage_uuid}

    Request

    Parameter type Description
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.

    Response

    If the update was successful, you will receive a 204 successful header response. You can preview the changes with a GET request to the same endpoint.

    ISO-Image Delete

    You can use this command to Delete an ISP Image

    client.ISOImage.remove("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/isoimages/{isoimage_uuid}
    

    Example response

    > HTTP/1.1 204 No Content
    

    DELETE https://api.gridscale.io/objects/isoimages/{isoimage_uuid}

    Response

    Once an ISP Image is deleted, you will receive a 204 header response as confirmation.

    Possible responses

    Response code Description
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The ISO Image does not exist.
    424 The current object state does not allow changes - see response body for more information.

    ISO-Image Events

    You can use this command to get a list of all the events on an ISO Image.

    client.ISOImage.events("x123xx1x-123x-1x12-123x-123xxx123x1x").then(function( res ) {
        console.log(res.result.events);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/isoimages/{isoimage_uuid}/events
    

    Example Response

    {
        "events": [
            {
                "request_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "timestamp": "2018-03-15T07:42:48Z",
                "request_status": "done",
                "object_type": "isoimage",
                "activity": "update",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "change": "Update ISO-Image test with: name=test2",
                "request_type": "isoimage_update",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
            },
            {
                "request_uuid": "bcc3e506-0f0b-4af2-a7d1-4c30f7828529",
                "timestamp": "2018-03-15T07:08:03Z",
                "request_status": "done",
                "object_type": "isoimage",
                "activity": "add",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "change": "Create new ISO-Image test",
                "request_type": "isoimage_add",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/isoimages/{isoimage_uuid}/events

    Response

    Parameter type Description
    create_time datetime The date and time when the request was received.
    user_uuid string The UUID of the User who triggered the request.
    object_type string Object type of the event that was triggered for (e.g. storage, server, ...).
    object_uuid string The object that was changed during the request.
    activity string The operation that was used on the object (e.g. update, remove, ...).
    change string What has been changed on the object.

    SSH Keys

    These keys, which are based on the RSA encryption protocol, consist of a public key and a private key. The public key is stored on all your systems while the private key remains on your client. You can also protect the private key with a passphrase. So if you now connect to one of your systems, you will no longer be asked for the password of the system, but after the passphrase of your private key. Once you have created such a key pair, you can even disable the login via passwords and make your server even more secure. gridscale even allows you to automatically place your public key on the servers of your choice. This means that you don’t even have to assign a password.

    for simplicity, we will use {sshkey} wherever an actual SSH key would be.

    SSH-Keys Get

    You can use this command to get a list of all SSH Keys

    client.SSHKey.list().then(function( res ) {
        console.log(res.result.sshkeys);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/sshkeys
    

    Example Response

    {
        "sshkeys": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "change_time": "2018-03-15T18:13:07Z",
                "status": "active",
                "sshkey": "{sshkey}",
                "name": "test",
                "labels": [],
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "create_time": "2018-03-15T18:13:07Z",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
            }
        }
    }
    }
    

    GET https://api.gridscale.io/objects/sshkeys

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    sshkey string The OpenSSH public key string (all key types are supported => ed25519, ecdsa, dsa, rsa, rsa1)
    status status indicates the status of the object.

    SSH-Key Create

    You can use this command to create a new SSH Key

    client.SSHKey.create({"name": "sshkey","sshkey": "{sshkey}}"}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "sshkey","sshkey": "{sshkey}}"}' \
         -X POST \
         https://api.gridscale.io/objects/sshkeys
    

    Example Request Body

    {
        "name": "sshkey",
        "sshkey": "{sshkey}}"
    }
    

    Example Response

    {
        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
        "request_uuid": "bcc3e506-0f0b-4af2-a7d1-4c30f7828529"
    }
    

    POST https://api.gridscale.io/objects/sshkeys

    Request

    A list of possible parameters for your POST request.

    Parameter type required Description
    name string required The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    sshkey string required sshkey_string is the OpenSSH public key string (all key types are supported => ed25519, ecdsa, dsa, rsa, rsa1)

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.

    SSH-Key Get

    You can use this request to get information regarding a specific SSH Key

    client.SSHKey.get("aa6e8749-0cdd-488f-90fd-418c818ca5f7").then(function( res ) {
        console.log(res.result.sshkey);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##"
         -H "X-Auth-Token: ##API-Token##"
         -X GET \
         https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}
    

    Example Response

    {
        "sshkey": {
            "labels": [],
            "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "create_time": "2018-03-15T19:18:11Z",
            "status": "active",
            "change_time": "2018-03-15T19:18:11Z",
            "name": "test2",
            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
            "sshkey": "{sshkey}"
        }
    }
    

    GET https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}

    Resonse

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    sshkey string sshkey_string is the OpenSSH public key string (all key types are supported => ed25519, ecdsa, dsa, rsa, rsa1).
    status status indicates the status of the object.

    SSH-Key Patch

    You can use this command to Update an SSH-Key

    client.SSHKey.patch("aa6e8749-0cdd-488f-90fd-418c818ca5f7", {name: "new name"}).then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "new name"}' \
         -X PATCH \
         https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}
    

    Example request body

    {
      "name": "new name"
    }
    

    Example header response

    < HTTP/1.1 204 Accepted
    

    PATCH https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}

    Request

    Parameter type Description
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    sshkey string sshkey_string is the OpenSSH public key string (all key types are supported => ed25519, ecdsa, dsa, rsa, rsa1).

    Response

    If the update was successful, you will receive a 204 successful header response. You can preview the changes with a GET request to the same endpoint.

    SSH-Key Delete

    You can use this command to Delete an SSH-Key

    client.SSHKey.remove("{sshkey_uuid}").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}
    

    Example response

    > HTTP/1.1 204 No Content
    

    DELETE https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}

    Response

    Once an SSH-Key is deleted, you will receive a 204 header response as confirmation.

    Possible responses

    Response code Description
    204 The server successfully processed the request, but there was nothing to return.
    400 Data send is not valid. The response body will contain more specific information.
    404 The SSH Key does not exist.
    424 The current object state does not allow changes - see response body for more information.

    SSH-Key Events

    You can use this command to get a list of all the events on an SSH Key.

    client.SSHKey.events("ad020c14-4519-4495-8dd5-40818d499701").then(function( res ) {
        console.log(res.result.events);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}/events
    

    Example Response

    {
        "events": [
            {
                "timestamp": "2018-03-15T19:18:11Z",
                "change": "Create new sshkey test2",
                "user_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "request_type": "sshkey_add",
                "object_type": "sshkey",
                "request_uuid": "a7d6d205-37dd-42e1-a166-b950c771bda9",
                "request_status": "done",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "activity": "add"
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/sshkeys/{sshkey_uuid}/events

    Response

    Parameter type Description
    create_time datetime The date and time when the request was received.
    user_uuid string The UUID of the User who triggered the request.
    object_type string Object type of the event that was triggered for (e.g. storage, server, ...).
    object_uuid string The object that was changed during the request.
    activity string The operation that was used on the object (e.g. update, remove, ...).
    change string What has been changed on the object.

    Locations

    The location defines which Data Center your objects will be running in, the full list of locations can be found by sending a GET request to the /locations endpoint. You will need the specify the location_uuid when creating many objects via the API.

    Locations Get

    You can use this command to get a list of all available Locations

    client.Location.list().then(function( res ) {
        console.log(res.result.locations);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations
    

    Example Response

    {
        "locations": {
            "45ed677b-3702-4b36-be2a-a2eab9827950": {
                "status": "active",
                "country": "de",
                "labels": [],
                "name": "de/fra",
                "object_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "iata": "fra"
            }
        }
    }
    

    GET https://api.gridscale.io/objects/locations

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    iata string Uses IATA airport code, which works as a location identifier.

    Location Get

    You can use this command to get information regarding a specific Location

    client.Location.get("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
          -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}
    

    Example Response

    {
        "location": {
            "iata": "fra",
            "status": "active",
            "labels": [],
            "name": "de/fra",
            "object_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
            "country": "de"
        }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    iata string Uses IATA airport code, which works as a location identifier.

    Loc-IP's Get

    You can use this request to get all of the IP Addresses available at a location.

    client.Location.getLocationIPs("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result.ips);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}/ips
    

    Example Response

    {
        "ips": {
            "67d773f2-4dce-466d-ab43-9ea8ce9f2f7e": {
                "ip": "123.123.12.1",
                "usage_in_minutes": 61922.0,
                "location_name": "de/fra",
                "change_time": "2018-02-01T13:48:10Z",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "delete_block": false,
                "partner_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "status": "active",
                "location_country": "de",
                "failover": false,
                "current_price": 3.71532,
                "create_time": "2018-02-01T13:48:10Z",
                "family": 4,
                "account_uuid": "28aaf836-5364-47a2-8766-a89513d8d898",
                "relations": {
                    "loadbalancers": [
                        {
                            "loadbalancer_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "create_time": "2018-02-27T13:35:08Z",
                            "loadbalancer_name": "test"
                        }
                    ],
                    "servers": []
                },
                "labels": [],
                "prefix": "123.123.12.1/32",
                "object_uuid": "67d773f2-4dce-466d-ab43-9ea8ce9f2f7e",
                "location_iata": "fra",
                "name": "Default IP",
                "reverse_dns": "static-123-123-123-123.ipv4.exampleserver.com"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}/ips

    Response

    Parameter type Description
    ip string The IP Address (v4 or v6).
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    family integer The IP Address family (v4 or v6).
    failover boolean Sets failover mode for this IP. If true, then this IP is no longer available for DHCP and can no longer be related to any server.
    reverse_dns string Defines the reverse DNS entry for the IP Address (PTR Resource Record).
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array List of servers related to this IP Address.
    delete_block boolean Defines if the object is administratively blocked. If true, it can not be deleted by the user.

    Loc-ISO's Get

    You can use this request to get all of the ISO Images available at a location.

    client.Location.getLocationISOImages("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result.isoimages);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}/isoimages
    

    Example Response

    {
        "isoimages": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "description": null,
                "location_iata": "fra",
                "change_time": "2017-10-26T16:01:58Z",
                "name": "OPNsense 17.7.5",
                "usage_in_minutes": 0,
                "current_price": 0.0,
                "create_time": "2017-10-25T12:56:54Z",
                "relations": {
                    "servers": []
                },
                "location_country": "de",
                "private": false,
                "capacity": 1,
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "source_url": "https://pascal-hoffmann.de/OPNsense-17.7.5-OpenSSL-dvd-amd64.iso",
                "location_name": "de/fra",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "status": "active",
                "version": null,
                "labels": []
            }
      }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}/isoimages

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    private boolean If the object is private, the value will be true. Otherwise the value will be false.
    version string Upstream version of the ISO-Image release
    description string Description of the ISO-Image release
    source_url string network_source_url contains the source URL of the ISO-Image that it was originally fetched from.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array List of servers related to this ISO-Image

    Loc-Networks Get

    You can use this request to get all of the Networks available at a location.

    client.Location.getLocationNetworks("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result.networks);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}/networks
    

    Example Response

    {
        "networks": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "public_net": true,
                "relations": {
                    "vlans": [],
                    "servers": [
                        {
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "create_time": "2018-03-14T13:33:13Z",
                            "mac": "16:f7:22:9e:56:01",
                            "ordering": 0,
                            "l3security": [],
                            "network_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "bootdevice": false,
                            "object_name": "Ubunto 16.04"
                        }
                    ]
                },
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_country": null,
                "l2security": true,
                "network_type": "network",
                "labels": [],
                "location_uuid": null,
                "status": "active",
                "delete_block": false,
                "name": "Public Network test",
                "create_time": "2018-02-01T10:53:54Z",
                "location_iata": null,
                "change_time": "2018-03-14T08:40:32Z",
                "location_name": null
            }
        }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}/networks

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    public_net boolean True if the network is public. If private it will be false. Each private network is a secure and fully transparent 2-Layer network between servers. There is no limit on how many servers can be connected to the same private network.
    l2security boolean Defines information about MAC spoofing protection (filters layer2 and ARP traffic based on MAC source). It can only be (de-)activated on a private network - the public network always has l2security enabled. It will be true if the network is public, and false if the network is private.
    delete_block boolean Defines if the object is administratively blocked. If true, it can not be deleted by the user.
    network_type network_type defines the type of a network. This may be "network", "mpls", "breakout" or "deleted". In partner level infrastructure, "mpls" and "breakout" can't be created or configured by the user.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    location_site integer Defines the numbering of the Data Centers on a given IATA location (e.g. where fra is the location_iata, the site is then 1, 2, 3, ...).
    relations array List of servers related to this network

    Loc-Servers Get

    You can use this request to get all of the Servers available at a location.

    client.Location.getLocationServers("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result.servers);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}/servers
    

    Example Response

    {
        "servers": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "legacy": false,
                "availability_zone": null,
                "location_iata": "fra",
                "location_name": "de/fra",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "power": true,
                "labels": [],
                "auto_recovery": true,
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "current_price": 3.77984,
                "console_token": "$console_token",
                "status": "active",
                "location_country": "de",
                "change_time": "2018-03-14T13:33:54Z",
                "create_time": "2018-03-14T13:33:13Z",
                "hardware_profile": "default",
                "name": "Ubunto 16.04",
                "cores": 2,
                "usage_in_minutes_cores": 5906,
                "usage_in_minutes_memory": 23624,
                "relations": {
                    "networks": [
                        {
                            "mcast": null,
                            "partner_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "mac": "16:f7:22:9e:56:01",
                            "ordering": 0,
                            "vxlan": null,
                            "l3security": [],
                            "l2security": true,
                            "firewall": null,
                            "public_net": true,
                            "vlan": null,
                            "firewall_template_uuid": null,
                            "create_time": "2018-03-14T13:33:13Z",
                            "network_type": "network",
                            "bootdevice": false,
                            "object_name": "Public Network test",
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "network_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
                        }
                    ],
                    "public_ips": [
                        {
                            "family": 4,
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "ip": "123.123.12.1",
                            "create_time": "2018-03-14T13:33:14Z",
                            "prefix": "123.123.12.1/32"
                        },
                        {
                            "family": 6,
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "ip": "123.123.12.1",
                            "create_time": "2018-03-14T13:33:16Z",
                            "prefix": "123.123.12.1/128"
                        }
                    ],
                    "isoimages": [],
                    "storages": [
                        {
                            "controller": 0,
                            "lun": 0,
                            "storage_type": "storage",
                            "capacity": 10,
                            "license_product_no": null,
                            "create_time": "2018-03-14T13:33:24Z",
                            "object_name": "Ubunto 16.04 Storage",
                            "bus": 0,
                            "bootdevice": true,
                            "last_used_template": "ec4ef18f-84df-42bb-b7c4-c2957635ee53",
                            "target": 0,
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x"
                        }
                    ]
                },
                "memory": 8
            }
        }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}/servers

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    cores integer Defines the number of server cores.
    memory integer The amount of server memory in GiB.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    console_token string Defines the token used by the panel to open the websocket VNC connection to the server console.
    legacy boolean Legacy-Hardware emulation instead of virtio hardware. If enabled, hotplugging cores, memory, storage, network, etc. will not work, but the server will most likely run every x86 compatible operating system. This mode comes with a performance penalty, as emulated hardware does not benefit from the virtio driver infrastructure.
    availability_zone Which Availability-Zone the Server is placed.
    auto_recovery boolean Defines if the server should be auto-started in case of a failure (default=true).
    current_price number The price for the current period since the last bill.
    relations array Objects related to this Server

    Loc-Snapshots Get

    You can use this request to get all of the Snapshots available at a location.

    client.Location.getLocationSnapshots("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result.snapshots);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}/snapshots
    

    Example Response

    {
        "snapshots": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "last_used_template": null,
                "status": "active",
                "name": "Ubunto 16.04 Storage Snapshot",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_country": "de",
                "location_iata": "fra",
                "change_time": "2018-03-16T14:57:57Z",
                "capacity": 10,
                "current_price": 0.0,
                "create_time": "2018-03-16T14:57:57Z",
                "parent_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "parent_name": "Ubunto 16.04 Storage",
                "usage_in_minutes": 0,
                "location_name": "de/fra",
                "labels": []
            }
        }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}/snapshots

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    status status indicates the status of the object.
    parent_uuid string UUID of the storage this snapshot was created from
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    last_used_template string Indicates the UUID of the last used template on this storage (inherited from snapshots).
    current_price number The price for the current period since the last bill.

    Loc-Storages Get

    You can use this request to get all of the Storages available at a location.

    client.Location.getLocationStorages("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result.storages);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}/storages
    

    Example Response

    {
        "storages": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "license_product_no": null,
                "change_time": "2018-03-14T13:33:13Z",
                "create_time": "2018-03-14T13:33:13Z",
                "current_price": 0.13112,
                "location_country": "de",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "parent_uuid": null,
                "usage_in_minutes": 29800,
                "storage_type": "storage",
                "capacity": 10,
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_name": "de/fra",
                "relations": {
                    "servers": [
                        {
                            "object_name": "Ubunto 16.04",
                            "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                            "create_time": "2018-03-14T13:33:24Z",
                            "target": 0,
                            "controller": 0,
                            "bootdevice": true,
                            "bus": 0,
                            "lun": 0
                        }
                    ],
                    "snapshot_schedules": []
                },
                "labels": [],
                "last_used_template": "ec4ef18f-84df-42bb-b7c4-c2957635ee53",
                "location_iata": "fra",
                "name": "Ubunto 16.04 Storage",
                "status": "active",
                "snapshots": [
                    {
                        "object_name": "Ubunto 16.04 Storage Snapshot",
                        "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                        "create_time": "2018-03-16T14:57:57Z",
                        "schedules_snapshot_name": null,
                        "schedules_snapshot_uuid": null,
                        "last_used_template": null,
                        "object_capacity": 10
                    }
                ]
            }
        }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}/storages

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    status status indicates the status of the object.
    parent_uuid string UUID of the storage this snapshot was created from
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    last_used_template string Indicates the UUID of the last used template on this storage (inherited from snapshots).
    current_price number The price for the current period since the last bill.

    Loc-Templates Get

    You can use this request to get all of the Templates available at a location.

    client.Location.getLocationTemplates("45ed677b-3702-4b36-be2a-a2eab9827950").then(function( res ) {
        console.log(res.result.templates);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/locations/{location_uuid}/templates
    

    Example Response

    {
        "templates": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "status": "active",
                "ostype": "windows",
                "version": "Windows Server 2016 Standard",
                "location_iata": "fra",
                "change_time": "2017-10-30T11:50:35Z",
                "private": false,
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "license_product_no": 800002,
                "create_time": "2016-10-24T14:50:23Z",
                "usage_in_minutes": 0,
                "name": "Windows Server 2016",
                "capacity": 32,
                "location_name": "de/fra",
                "distro": "Windows Server",
                "description": "SPLA-Licensed",
                "current_price": 0.0,
                "location_country": "de"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/locations/{location_uuid}/templates

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    ostype The operating system installed in the template.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    status Status indicates the status of the object.
    private boolean If the object is private, the value will be true. Otherwise the value will be false.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    version string Upstream version of the Template operating system
    description string Description of the Template
    current_price number The price for the current period since the last bill.
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details)

    Object Storages

    Our Object storage offers you an S3 compatible HTTP interface which allows you to use applications designed for the Amazon S3 storage server - without any customization. We use the same data storage principles for our Object Storage as we do for our Storages, your data will be stored threefold, in different availability zones.

    With our bucket explorer, you can directly access all your data through our GUI, upload and manage all of your data from within your web browser.

    {access_key} & {secret_key} will be substituted for simplicity.

    Access Keys Get

    You can use this command to get a list of all your access keys

    client.ObjectStorage.accessKeys().then(function( res ) {
        console.log(res.result.access_keys);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/objectstorages/access_keys
    

    Example Response

    {
        "access_keys": [
            {
                "secret_key": "{secret_key}",
                "access_key": "{access_key}"
            },
            {
                "secret_key": "{secret_key}",
                "access_key": "{access_key}"
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/objectstorages/access_keys

    Response

    Parameter type Description
    access_key string The object storage access_key
    secret_key string The object storage secret_key
    user string Account this credentials belong to.

    Access Key Create

    You can use this command to automatically generate new Access Keys

    client.ObjectStorage.createAccessKey().then(function( res ) {
        console.log(res.result.access_key);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X POST \
         https://api.gridscale.io/objects/objectstorages/access_keys
    

    Example response

    {
        "access_key": {
            "access_key": "{access_key}",
            "secret_key": "{secret_key}"
        },
        "request_uuid": "da80d4ac-bb7a-4562-8100-9954cc962a41"
    }
    

    Response

    Parameter type Description
    access_key string The object storage access_key
    secret_key string The object storage secret_key
    user string Account this credentials belong to.
    request_uuid string The unique id for the request.

    Access Key Get

    You can use this command to get detailed information regarding an access_key

    client.ObjectStorage.accessKey("{access_key}").then(function( res ) {
        console.log(res.result.access_key);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/objectstorages/access_keys/{accesskey}
    

    Example Response

    {
        "access_key": {
            "secret_key": "{secret_key}",
            "access_key": "{access_key}"
        }
    }
    

    GET https://api.gridscale.io/objects/objectstorages/access_keys/{accesskey}

    Response

    Parameter type Description
    access_key string The object storage access_key
    secret_key string The object storage secret_key
    user string Account this credentials belong to.

    Access Key Delete

    You can use this command to delete a specific access_key

    client.ObjectStorage.removeAccessKey("{access_key}").then(function( res ) {
        console.log(res.success);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/objectstorages/access_keys/{accesskey}
    

    Example response

    > HTTP/1.1 204 No Content
    

    GET https://api.gridscale.io/objects/objectstorages/access_keys/{accesskey}

    Response

    Once a Key is deleted, you will receive a 204 header response as confirmation.

    Possible responses

    Response code Description
    204 The server successfully processed the request, but there was nothing to return.
    404 The Network does not exist.
    424 The current object state does not allow changes - see response body for more information.

    Buckets Get

    You can use this command to get a list of all your Buckets

    client.ObjectStorage.buckets().then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/objectstorages/buckets
    

    Example Response

    {
        "buckets": [
            {
                "name": "bucket",
                "usage": {
                    "size_kb": 332355553,
                    "num_objects": 149
                }
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/objectstorages/buckets

    Response

    Parameter type Description
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    usage object The current usage of the bucket.
    size_kb integer The size of the the bucket (in kb)
    num_objects integer The number of files in the bucket

    Bucket Get

    You can use this command to get information regarding a specific bucket

    // coming soon
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/objectstorages/buckets/{bucket_name}
    

    Example Response

    {
        "buckets": [
            {
                "name": "bucket",
                "usage": {
                    "size_kb": 39,
                    "num_objects": 1
                }
            }
        ]
    }
    

    GET https://api.gridscale.io/objects/objectstorages/buckets/{bucket_name}

    Response

    Parameter type Description
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    usage object The current usage of the bucket.
    size_kb integer The size of the the bucket (in kb)
    num_objects integer The number of files in the bucket

    Bucket Contents

    Getting started

    npm install aws-sdk
    
    # download and install via the link on the left
    

    once installed

    // in server.js for example
    var AWS = require('aws-sdk');
    // you can then set the clients defaults
    var s3 = new AWS.S3({
            accessKeyId: "{yourAccessKeyId}",
            secretAccessKey: "{yourSecretAccessKey}",
            region: "eu-west-1",
            endpoint: 'gos3.io',
    });
    
    // now specify the bucket or other details
    var params = {
      Bucket: "test",
     };
    
     // then call the function to list the items inside the bucket 
    s3.listObjectsV2(params, function(err, data) {
    if (err) console.log(err, err.stack); // an error occurred
    else     console.log(data);           // successful response
    });
    
    
    # configure s3cmd
    
    s3cmd --configure
    
    # you will be promted for your accessKeyId, SecretKey, region, endpoint and dns+hostname
    # see the table to the left for the correct values
    # once configured and the test has passed you can then query for a list of buckets
    
    s3cmd ls
    
    # example response
    
    > 2018-03-16 19:41  s3://testBucket1
    > 2018-03-16 19:34  s3://testBucket2
    > 2018-03-16 20:19  s3://testBucket3
    

    Our Bucket storage follows the S3 Standard, meaning that you are able to use s3 compatible tools to work with your Buckets, Below we will show you how to get started.

    If working with shell, first download and install s3cmd ( requires python )

    If using JavaScript / NodeJS run npm install -g s3 -> View the Docs here;

    Values for Authentication

    Parameter type value
    access Key string Your Key, which can be found in the Object Storage section of the panel
    Secret Key string Your Secret, which can be found in the Object Storage section of the panel
    endpoint string gos3.io
    dns+hostname 'string' gos3.io
    region string eu-west-1

    After authenticating the bucket you can follow the guides above to work with your files.

    Deleted

    Objects that are deleted are no longer visible on their regular endpoints. For historical reasons these objects are still available read-only on a special endpoint named /deleted. If objects have been deleted but have not yet been billed in the current period, the yet-to-be-billed price is still shown.

    Deleted IP's

    You can use this command to GET all deleted IP Addresses

    client.Deleted.ips().then(function( res ) {
        console.log(res.result.deleted_ips);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/deleted/ips
    

    Example Response

    {
        "deleted_ips": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "ip": "123.123.12.1",
                "location_country": "de",
                "reverse_dns": "static-123-123-123-123.ipv4.exampleserver.com",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_name": "de/fra",
                "status": "deleted",
                "family": 4,
                "usage_in_minutes": 59025,
                "failover": false,
                "current_price": 3.5415,
                "location_iata": "fra",
                "labels": [],
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/deleted/ips

    Response

    Parameter type Description
    ip string Defines the IP Address (v4 or v6).
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    family Defines the IP Address family (v4 or v6).
    failover boolean Sets failover mode for this IP. If true, then this IP is no longer available for DHCP and can no longer be related to any server.
    reverse_dns string Defines the reverse DNS entry for the IP Address (PTR Resource Record).
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array List of servers related to this IP Address.
    delete_block boolean Defines if the object is administratively blocked. If true, it can not be deleted by the user

    Deleted ISO's

    You can use this command to GET all deleted ISO Images

    client.Deleted.isoimages().then(function( res ) {
        console.log(res.result.deleted_isoimages);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/deleted/isoimages
    

    Example Response

    {
        "deleted_isoimages": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "usage_in_minutes": 0,
                "private": true,
                "status": "deleted",
                "version": null,
                "name": "test",
                "create_time": "2018-03-14T13:17:02Z",
                "change_time": "2018-03-19T08:06:31Z",
                "source_url": "http://releases.ubuntu.com/16.04.4/ubuntu-16.04.4-server-amd64.iso?_ga=2.188975915.108704605.1521033305-403279979.1521033305",
                "description": null,
                "location_iata": "fra",
                "location_country": "de",
                "location_name": "de/fra",
                "capacity": 1,
                "current_price": 0.0
            }
        }
    }
    

    GET https://api.gridscale.io/objects/deleted/isoimages

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    private boolean If the object is private, the value will be true. Otherwise the value will be false.
    version string Upstream version of the ISO-Image release
    description string Description of the ISO-Image release
    source_url string Contains the source URL of the ISO-Image that it was originally fetched from.
    status Indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array List of servers related to this ISO-Image

    Deleted Networks

    You can use this command to GET all deleted Networks

    client.Deleted.networks().then(function( res ) {
        console.log(res.result.deleted_networks);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##"
         -H "X-Auth-Token: ##API-Token##"
         -X GET \
         https://api.gridscale.io/objects/deleted/networks
    

    Example Response

    {
        "deleted_networks": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "location_name": "de/fra",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "create_time": "2018-03-14T08:04:16Z",
                "public_net": false,
                "location_iata": "fra",
                "change_time": "2018-03-14T08:32:57Z",
                "status": "deleted",
                "usage_in_minutes": 0,
                "name": "test",
                "current_price": 0.0,
                "location_country": "de",
                "labels": []
            }
        }
    }
    

    GET https://api.gridscale.io/objects/deleted/networks

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    public_net boolean True if the network is public. If private it will be false. Each private network is a secure and fully transparent 2-Layer network between servers. There is no limit on how many servers can be connected to the same private network.
    l2security boolean Defines information about MAC spoofing protection (filters layer2 and ARP traffic based on MAC source). It can only be (de-)activated on a private network - the public network always has l2security enabled. It will be true if the network is public, and false if the network is private.
    delete_block boolean Defines if the object is administratively blocked. If true, it can not be deleted by the user.
    network_type network_type defines the type of a network. This may be "network", "mpls", "breakout" or "deleted". In partner level infrastructure, "mpls" and "breakout" can't be created or configured by the user.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    labels array List of labels.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    location_site integer Defines the numbering of the Data Centers on a given IATA location (e.g. where fra is the location_iata, the site is then 1, 2, 3, ...).
    relations array List of servers related to this network

    Deleted Servers

    You can use this command to GET all deleted Servers

    client.Deleted.servers().then(function( res ) {
        console.log(res.result.deleted_serversq);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/deleted/servers
    

    Example Response

    {
        "deleted_servers": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "cores": 1,
                "location_name": "de/fra",
                "usage_in_minutes_memory": 31782,
                "change_time": "2018-02-09T13:33:16Z",
                "console_token": "5f9c1ae17f7fa22128715ad1e9345a9c249d0db3c8276ac2ad7878fb7a7a407d9606b2b1bff97b62bb46397a62b80901",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "status": "deleted",
                "location_country": "de",
                "power": false,
                "usage_in_minutes_cores": 17296,
                "current_price": 8.264289999999997,
                "memory": 1,
                "labels": [],
                "create_time": "2018-02-01T13:49:39Z",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_iata": "fra",
                "name": "LAMP server"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/deleted/servers

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    cores integer Defines the number of server cores.
    memory integer The amount of server memory in GiB.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    console_token string Defines the token used by the panel to open the websocket VNC connection to the server console.
    legacy boolean Legacy-Hardware emulation instead of virtio hardware. If enabled, hotplugging cores, memory, storage, network, etc. will not work, but the server will most likely run every x86 compatible operating system. This mode comes with a performance penalty, as emulated hardware does not benefit from the virtio driver infrastructure.
    availability_zone Which Availability-Zone the Server is placed.
    auto_recovery boolean Defines if the server should be auto-started in case of a failure (default=true).
    current_price number The price for the current period since the last bill.
    relations array Objects related to this Server

    Deleted Snapshots

    You can use this command to GET all deleted Snapshots

    client.Deleted.snapshots().then(function( res ) {
        console.log(res.result.deleted_snapshots);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/deleted/snapshots
    

    Example Response

    {
        "deleted_snapshots": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "usage_in_minutes": 39420,
                "location_name": "de/fra",
                "parent_name": null,
                "create_time": "2018-03-16T14:57:57Z",
                "location_country": "de",
                "parent_uuid": null,
                "status": "deleted",
                "location_iata": "fra",
                "name": "Ubunto 16.04 Storage Snapshot",
                "last_used_template": null,
                "change_time": "2018-03-19T08:40:44Z",
                "capacity": 10,
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "labels": [],
                "current_price": 0.043362
            }
        }
    }
    

    GET https://api.gridscale.io/objects/deleted/snapshots

    Response

    Parameter type Description
    object_uuid: (string) The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    labels array List of labels.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    status status indicates the status of the object.
    parent_uuid string UUID of the storage this snapshot was created from
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    last_used_template string Indicates the UUID of the last used template on this storage (inherited from snapshots).
    current_price number The price for the current period since the last bill.

    Deleted Storages

    You can use this command to GET all deleted Storages

    client.Deleted.storages().then(function( res ) {
        console.log(res.result.deleted_storages);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/deleted/storages
    

    Example Response

    {
        "deleted_storages": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "parent_uuid": null,
                "location_iata": "fra",
                "capacity": 5,
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "location_name": "de/fra",
                "name": "test",
                "current_price": 0.00352,
                "labels": [],
                "create_time": "2018-03-13T12:09:12Z",
                "status": "deleted",
                "last_used_template": null,
                "change_time": "2018-03-13T13:36:56Z",
                "usage_in_minutes": 800,
                "location_country": "de"
            }
        }
    }
    

    GET https://api.gridscale.io/objects/deleted/storages

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    storage_type (one of storage, storage_high, storage_insane)
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details).
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    labels array List of labels.
    status status indicates the status of the object.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    current_price number The price for the current period since the last bill.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    relations array Objects related to this Storage

    Deleted Templates

    You can use this command to GET all deleted Templates

    client.Deleted.templates().then(function( res ) {
        console.log(res.result.deleted_templates);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##"
         -H "X-Auth-Token: ##API-Token##"
         -X GET \
         https://api.gridscale.io/objects/deleted/templates
    

    Example Response

    {
        "deleted_templates": {
            "x123xx1x-123x-1x12-123x-123xxx123x1x": {
                "version": null,
                "private": true,
                "name": "test",
                "object_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
                "ostype": null,
                "location_country": "de",
                "create_time": "2018-03-16T14:58:16Z",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "status": "deleted",
                "current_price": 0.0,
                "location_name": "de/fra",
                "capacity": 10,
                "change_time": "2018-03-19T09:12:13Z",
                "description": null,
                "location_iata": "fra",
                "usage_in_minutes": 0
            }
        }
    }
    

    GET https://api.gridscale.io/objects/deleted/templates

    Response

    Parameter type Description
    object_uuid string The UUID of an object is always unique, and refers to a specific object.
    name string The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.
    ostype The operating system installed in the template.
    location_uuid string Helps to identify which datacenter an object belongs to.
    location_name string The human-readable name of the location. It supports the full UTF-8 charset, with a maximum of 64 characters.
    location_country string Formatted by the 2 digit country code (ISO 3166-2) of the host country.
    location_iata string Uses IATA airport code, which works as a location identifier.
    capacity integer The capacity of a storage/ISO-Image/template/snapshot in GB.
    status status indicates the status of the object.
    private boolean If the object is private, the value will be true. Otherwise the value will be false.
    create_time datetime Defines the date and time the object was initially created.
    change_time datetime Defines the date and time of the last object change.
    version string Upstream version of the Template operating system
    description string Description of the Template
    current_price number The price for the current period since the last bill.
    license_product_no integer If a template has been used that requires a license key (e.g. Windows Servers) this shows the product_no of the license (see the /prices endpoint for more details).

    Cloud Automation

    Cloud Automation helps you to automate and optimize time consuming processes. You can set up tasks to be notified of changes in your infrastructure in real time.

    We are working on expanding the Cloud Automation Service so you can scale automatically according to your needs, you will be able to choose how your infrastructure adapts to different situations.

    Tasks Get

    You can use this command to get a list of all your tasks

    client.CAS.tasks.list().then(function( res ) { 
        console.log(res.response);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/cas/tasks
    

    Example Response

    {
    "tasks": {
        "ab48e37b-edeb-4f6a-8193-16ef5400e122": {
            "action_type": "send_email",
            "change_time": "2018-04-10T08:14:07Z",
            "status": "active",
            "labels": [
                "test"
            ],
            "object_uuid": "ab48e37b-edeb-4f6a-8193-16ef5400e122",
            "name": "test2",
            "event_type": "server_add",
            "action_payload": {
                "subject": "test",
                "to": "example@example.com",
                "from": "example@example.com"
            },
            "active": true,
            "filters": [
                {
                    "operator": "<",
                    "field": "memory",
                    "comparison_value": 1
                }
            ],
            "create_time": "2018-04-10T08:14:07Z"
        },
      }
    }
    

    GET https://api.gridscale.io/objects/cas/tasks

    Response

    Parameter type Description
    action_type string A keyword describing the event executed when the task is triggered
    name string The name of the task
    event_type string The event that will trigger the task
    action_payload array An array detailing the action that will be fired when the event_type that meets the filters requirements is executed on the account
    active boolean Defines if this task is currently active

    Filters (in response)

    Parameter type Description
    filters array[object] This defines what values need to be met to fire the action_payload, when the event_type is triggered.
    operator string The defining operator for the filter, in this case the action payload will trigger when a server is started with a memory less than 1
    field string Defines the resource to be filtered
    comparison_value The value to compare against the field e.g. if field operator comparison_value == True then fire the action_payload

    Task Get

    You can use this command to get information regarding a specific task

    client.CAS.tasks.get("ab48e37b-edeb-4f6a-8193-16ef5400e122").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/cas/tasks/{task_uuid}
    

    Example Response

    {
        "tasks": {
            "ab48e37b-edeb-4f6a-8193-16ef5400e122": {
                "action_type": "send_email",
                "change_time": "2018-04-10T08:14:07Z",
                "status": "active",
                "labels": [
                    "test"
                ],
                "object_uuid": "ab48e37b-edeb-4f6a-8193-16ef5400e122",
                "name": "test2",
                "event_type": "server_add",
                "action_payload": {
                    "subject": "test",
                    "to": "example@example.com",
                    "from": "example@example.com"
                },
                "active": true,
                "filters": [
                    {
                        "operator": "<",
                        "field": "memory",
                        "comparison_value": 1
                    }
                ],
                "create_time": "2018-04-10T08:14:07Z"
            }
      }
    }
    

    GET https://api.gridscale.io/objects/cas/tasks/{task_uuid}

    Response

    Parameter type Description
    action_type string A keyword describing the event executed when the task is triggered either: 'send_email', 'http_request' or 'send_slack'
    name string The name of the task
    event_type string The event that will trigger the task
    action_payload array An array detailing the action that will be fired when the event_type that meets the filters requirements is executed on the account
    active boolean Defines if this task is currently active

    Filters (in response)

    Parameter type Description
    filters array[object] This defines what values need to be met to fire the action_payload, when the event_type is triggered. and contains the following three parameters.
    operator string The defining operator for the filter, in this case the action payload will trigger when a server is started with a memory less than 1
    field string Defines the resource to be filtered
    comparison_value The value to compare against the field e.g. if field operator comparison_value == True then fire the action payload

    Task Create

    You can use this a command like this to Create a Task, but first you will need to have a look at the different types of action_payloads, so you can create your own.

    client.CAS.tasks.create({"action_payload": { "...":"..."},"name": "dashboard notification HTTP","labels": ["httpNotification"],"filters": [],"action_type": "http_request","active": true,"event_type": "server_update"}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"action_payload": { "...":"..."},"name": "dashboard notification HTTP","labels": ["httpNotification"],"filters": [],"action_type": "http_request","active": true,"event_type": "server_update"}' \
         -X POST \
         https://api.gridscale.io/objects/cas/tasks
    

    Example request body

    {
        "action_payload": {
            "... see more about the action_payload in the table to the left"
        },
        "name": "dashboard notification HTTP",
        "labels": ["httpNotification"],
        "status": "active",
        "filters": [],
        "action_type": "http_request",
        "active": true,
        "event_type": "server_update"
    }
    

    Request

    Parameter type required Description
    action_type required One of three values send_email, send_slack or http_request. Each of these will require a different set of values to be sent in the POST request. see the list here.
    name string required Name of the task
    labels array[string] List of labels for this server - allows you to group objects into projects.
    filters array{} required The parameters that the event event_type will have to pass in order for the action_payload to be fired.
    action_payload required The payload you would like to fire if the event_types values pass the filters. see more here.
    event_type string required The event_type you would like to track - you can find a list of all possible values here.

    Task Delete

    To delete a task via API, just send a delete request to the /cas/tasks/{cas_uuid} endpoint

    You can use this command to Create a Task

    client.CAS.tasks.remove("cas_uuid").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/cas/tasks/{cas_uuid}
    

    response

    A header response of 204 and No Content signifies a successful DELETE request.

    Task Update

    In this example, we will update an existing task to send us a slack message when a server is started with over 8 cores and 16GB of memory.

    You can use this example to make the request

    client.CAS.tasks.patch("cas_uuid", {"task": {"active": true, "executing_user_uuid": null, "filters": [{"comparison_value": 8, "operator": ">=", "field": "cores"}, {"comparison_value": 16, "operator": ">=", "field": "memory"}], "object_uuid": "525ca128-9824-4d0d-9adb-618a7138d88a", "partner_uuid": "95a2980b-7012-43dd-81f2-07577cfcb9f0", "create_time": "2018-04-10T13:52:30Z", "change_time": "2018-04-13T17:41:52Z", "event_type": "server_add", "executing_user_token": null, "action_type": "send_slack", "name": "slackupdate", "labels": ["limitMax", "Devserver"], "action_payload": {"message": {"text": "A server with ${cores} cores and ${memory} memory has been started, exceeding our maximum limits"}, "webhook_url": "https://your.slack.hook/services/youruniqueurl"}}}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-Type: application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"task": {"active": true, "executing_user_uuid": null, "filters": [{"comparison_value": 8, "operator": ">=", "field": "cores"}, {"comparison_value": 16, "operator": ">=", "field": "memory"}], "object_uuid": "525ca128-9824-4d0d-9adb-618a7138d88a", "partner_uuid": "95a2980b-7012-43dd-81f2-07577cfcb9f0", "create_time": "2018-04-10T13:52:30Z", "change_time": "2018-04-13T17:41:52Z", "event_type": "server_add", "executing_user_token": null, "action_type": "send_slack", "name": "slackupdate", "labels": ["limitMax", "Devserver"], "action_payload": {"message": {"text": "A server with ${cores} cores and ${memory} memory has been started, exceeding our maximum limits"}, "webhook_url": "https://your.slack.hook/services/youruniqueurl"}}}' \
         -X PATCH \
         https://api.gridscale.io/objects/cas/tasks/{cas_uuid}
    

    request body

    {
    "task": {
        "action_type": "send_slack",
        "event_type": "server_add",
        "filters": [
            {
                "comparison_value": 8,
                "field": "cores",
                "operator": ">="
            },
            {
                "comparison_value": 16,
                "field": "memory",
                "operator": ">="
            }
        ],
        "labels": [
            "uk_site",
            "production"
        ],
        "action_payload": {
            "webhook_url": "https://your.slack.hook/services/youruniqueurl",
            "message": {
                "text": "A server with ${cores} cores and ${memory} memory has been started, exceeding our maximum limits"
            }
        },
        "name": "testslack",
    }
    }
    

    Something left out the the previous POST request example was the filters[] section. This allows you to filter out certain scenarios, so you only get the notifications you want. Here, we have set 2 filters:

    if (server is started with cores >= 8 && memory >= 16)

    => send action_payload

    Variable injection

    We have also injected two variables into our message, ${cores} & ${memory} which will be set as the values for the amount of cores and memory the server was started with.

    Request

    Parameter type required Description
    action_type required One of three values send_email, send_slack or http_request. Each of these will require a different set of values to be sent in the POST request. see the list here.
    name string required Name of the task
    labels array[string] List of labels for this server - allows you to group objects into projects.
    filters array{} required The parameters that the event event_type will have to pass in order for the action_payload to be fired.
    action_payload required The payload you would like to fire if the event_types values pass the filters. see more here.
    event_type string required The event_type you would like to track - you can find a list of all possible values here.

    Events, Filters & Variables

    Each endpoint has different event types & variables, and each event type has a different list of available filters.

    An example of the servers event_types and it's filters. To understand best, Compare this example response against the table to the left

    "server_add": {
        "legacy": {
            "description": "",
            "type": "boolean"
        },
        "server_uuid": {
            "required": true,
            "nullable": false,
            "description": "",
            "type": "uuid"
        },
        "hardware_profile": {
            "allowed": [
                "default",
                "nested",
                "legacy",
                "cisco_csr",
                "sophos_utm",
                "f5_bigip",
                "q35",
                "q35_nested"
            ],
            "type": "string"
        },
        "auto_recovery": {
            "description": "",
            "type": "boolean"
        },
        "cores": {
            "min": 1,
            "required": true,
            "description": "",
            "type": "integer",
            "max": 64
        },
        "name": {
            "maxlength": 64,
            "type": "string",
            "empty": false,
            "required": true,
            "minlength": 1,
            "description": ""
        },
        "memory": {
            "min": 1,
            "required": true,
            "description": "",
            "type": "integer",
            "max": 192
        },
        "availability_zone": {
            "allowed": [
                null,
                "a",
                "b"
            ],
            "nullable": true,
            "description": "",
            "type": "string"
        },
        "labels": {
            "maxlength": 64,
            "unique": true,
            "description": "",
            "type": "list",
            "schema": {
                "maxlength": 64,
                "description": "",
                "type": "string"
            }
        },
        "location_uuid": {
            "required": true,
            "description": "",
            "type": "uuid"
        }
    },
    "server_power_shutdown": {
        "server_uuid": {
            "required": true,
            "description": "",
            "type": "uuid"
        }
    },
    "server_relation_ipaddr_add": {
        "bootdevice": {
            "description": "",
            "type": "boolean"
        },
        "server_uuid": {
            "required": true,
            "description": "",
            "type": "uuid"
        },
        "isoimage_uuid": {
            "required": true,
            "description": "",
            "type": "uuid"
        }
    },
    "server_remove": {
        "server_uuid": {
            "required": true,
            "description": "",
            "type": "uuid"
        }
    }
    

    Servers

    Event Type Filters (required?) type
    server_add
    • auto_recovery boolean
    • availability_zone string
    • cores (required) int
    • hardware_profile string
    • labels list
    • legacy boolean
    • location_uuid (required) string
    • memory (required) int
    • name (required) string
    • server_uuid (required) string
    server_power_shutdown
    • server_uuid (required) string
    server_power_update
    • auto_trigger boolean
    • power (required) boolean
    • server_uuid (required) string
    server_relation_ipaddr_add
    • bootdevice boolean
    • ipaddr_uuid (required) string
    • server_uuid (required) string
    server_relation_ipadd_remove
    • ipaddr_uuid (required) string
    • server_uuid (required) string
    server_relation_isoimage_add bootdevice booleanisoimage_uuid (required) stringserver_uuid (required) string
    server_relation_isoimage_remove isoimage_uuid (required) stringserver_uuid (required) string
    server_relation_isoimage_update bootdevice booleanisoimage_uuid (required) stringserver_uuid (required) string
    server_relation_network_add
    • bootdevice boolean
    • firewall dict
    • rules-v4-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v4-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • firewall_template_uuid string
    • l3security list
    • network_uuid (required) string
    • order (required) inting int
    • server_uuid (required) string
    server_relation_network_remove network_uuid (required) stringserver_uuid (required) string
    server_relation_network_update
    • bootdevice boolean
    • firewall dict
    • rules-v4-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v4-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • firewall_template_uuid string
    • l3security list
    • network_uuid (required) string
    • order (required) inting int
    • server_uuid (required) string
    server_relation_storage_add bootdevice booleanstorage_uuid (required) stringserver_uuid (required) string
    server_relation_storage_remove storage_uuid (required) stringserver_uuid (required) string
    server_relation_storage_update bootdevice booleanstorage_uuid (required) stringserver_uuid (required) string
    server_remove server_uuid (required) string
    server_update
    • auto_recovery boolean
    • availability_zone string
    • cores (required) int
    • hardware_profile string
    • labels list
    • legacy boolean
    • location_uuid (required) string
    • memory (required) int
    • name (required) string
    • server_uuid (required) string

    json representation of the storage_add.templates filter

    "template": {
        "type": "dict",
        "schema": {
            "private": {
                "type": "boolean"
            },
            "hostname": {
                "type": "hostname"
            },
            "sshkeys": {
                "type": "list",
                "schema": {
                    "type": "string"
                },
                "unique": true
            },
            "password_type": {
                "type": "string",
                "allowed": [
                    "plain",
                    "crypt"
                ],
                "dependencies": [
                    "password"
                ]
            },
            "password": {
                "type": "string",
                "empty": false,
                "dependencies": [
                    "password_type"
                ]
            },
            "template_uuid": {
                "type": "uuid",
                "required": true
            }
        }
    }
    

    Storages

    Event Type Filters (required?) type
    storage_add
    • capacity (required) int
    • labelslist
    • location_uuid (required) string
    • name string
    • storage_type string
    • storage_uuid (required) string
    • template dict
      • hostname string
      • password string
      • password_type string
      • private boolean
      • sshkeys list
      • template_uuid string
    storage_remove storage_uuid (required) string
    storage_update capacity int, labels list, name string, storage_uuid (required) string

    Networks

    Event Type Filters (required?) type
    network_add l2security boolean, labels list, location_uuid (required) string, name (required) string, network_uuid (required) string
    network_remove network_uuid (required) string
    network_update l2security boolean, labels list, name (required) string, network_uuid (required) string

    json representation of the available optoins to filter your firewall

    "protocol": {
        "type": "string",
        "allowed": [
            "udp",
            "tcp"
        ],
        "nullable": true
    },
    "dst_cidr": {
        "type": "ip6net",
        "nullable": true
    },
    "src_port": {
        "type": "portrange",
        "nullable": true
    },
    "src_cidr": {
        "type": "ip6net",
        "nullable": true
    },
    "order": {
        "type": "integer",
        "required": true,
        "min": 0
    },
    "dst_port": {
        "type": "portrange",
        "nullable": true
    },
    "action": {
        "type": "string",
        "required": true,
        "allowed": [
            "accept",
            "drop"
        ]
    }
    

    Firewalls

    Event Type Filters (required?) type
    firewall_add firewall_uuid (required) string, labels list, name (required) string, rules dict
    • rules-v4-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v4-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    firewall_remove firewall_uuid (required) string
    firewall_update firewall_uuid (required) string, labels list, name (required) string, rules dict
    • rules-v4-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v4-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-in dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange
    • rules-v6-out dict
      • action (required) string
      • dst_cidr ip4net
      • dst_port portrange
      • order (required) int
      • protocol string
      • src_cidr ip4net
      • src_port portrange

    IP Adresses

    Event Type Filters (required?) type
    ipaddr_add failover boolean, family (required) int, ipaddr_uuid (required) string, labels list, location_uuid (required) string, reverse_dns string
    ipaddr_remove ipaddr_uuid (required) string
    ipaddr_update failover boolean, ipaddr_uuid (required) string, labels list, reverse_dns string

    Load Balancers

    Event Type Filters (required?) type
    loadbalancer_add
    • algorithm (required) string
    • backend_servers (required) list
    • weight (required) int
    • forwarding_rules (required) dict
      • letsencrypt_ssl (required) domainname
      • listen_port (required) port
      • mode (required) string
      • target_port (required) port
    • labels list
    • lb_uuid (required) string
    • listen_ipv4_uuid (required) string
    • listen_ipv6_uuid (required) string
    • location_uuid (required) string
    • name (required) string
    • redirect_http_to_https (required) boolean
    loadbalancer_remove lb_uuid (required) string
    loadbalancer_update
    • algorithm (required) string
    • backend_servers (required) list
    • weight (required) int
    • forwarding_rules (required) dict
      • letsencrypt_ssl (required) domainname
      • listen_port (required) port
      • mode (required) string
      • target_port (required) port
    • labels list
    • lb_uuid (required) string
    • listen_ipv4_uuid (required) string
    • listen_ipv6_uuid (required) string
    • location_uuid (required) string
    • name (required) string
    • redirect_http_to_https (required) boolean

    Snapshots

    Event Type Filters (required?) type
    snapshot_add labels list, name string, snapshot_uuid (required) string, storage_uuid (required) string
    snapshot_export_to_s3 s3auth:{access_key, host, secretkey} (required) dict , s3data:{bucket, filename, host, private} (required) dict, snapshot_uuid (required) string, storage_uuid (required) string
    snapshot_remove storage_uuid (required) string, snapshot_uuid (required) string
    snapshot_rollback rollback (required) boolean, snapshot_uuid (required) string, storage_uuid (required) string
    snapshot_update labels list, name string, snapshot_uuid (required) string, storage_uuid (required) string

    Schedules

    Event Type Filters (required?) type
    schedule_snapshot_add keep_snapshots (required) int, labels list, name (required) string, next_runtime iso8601, run_interval (required) int, schedule_uuid (required) string, storage_uuid (required) string
    schedule_snapshot_perform schedule_uuid (required) string
    schedule_snapshot_remove schedule_uuid (required) string, storage_uuid (required) string
    schedule_snapshot_update keep_snapshots (required) int, labels list, name (required) string, next_runtime iso8601, run_interval (required) int, schedule_uuid (required) string, storage_uuid (required) string

    SSH Keys

    Event Type Filters (required?) type
    sshkey_add labels list, name string, sshkey (required) string, sshkey_uuid (required) string
    sshkey_remove sshkey_uuid (required) string
    sshkey_update labels list, name string, sshkey (required) string, sshkey_uuid (required) string

    ISO Images

    Event Type Filters (required?) type
    isoimage_add labels list, name string, name (required) string, isoimage_uuid (required) string, location_uuid (required) string, source_url (required) url
    sshkey_remove isoimage_uuid (required) string
    sshkey_update labels list, name string, name (required) string, isoimage_uuid (required) string

    Marketplace Templates

    Event Type Filters (required?) type
    marketplace_template_add capacity (required) int, name string, labels list, template_uuid (required) string, object_storage_path (required) string
    marketplace_template_import unique_hash (required) string
    marketplace_template_remove template_uuid (required) string
    marketplace_template_update capacity (required) int, name string, labels list, template_uuid (required) string, object_storage_path (required) string

    Templates

    Event Type Filters (required?) type
    template_update name string, labels list, template_uuid (required) string
    template_remove template_uuid (required) string
    template_add labels list, name string, snapshot_uuid (required) string, template_uuid (required) string

    Variables

    Every endpoint has event_types, every event_type has a different list of filters, and each event_type's filters can be injected into the action payload, while ${datetime} and ${event_type} are always available.

    Events Get

    Once you have finished learning the basics of how to use the CAS API, you can use this endpoint to learn more about what you can do with the API.

    You can use this command to get a list of all the possible events per resource

    client.CAS.events.list().then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/cas/events
    

    Response

    Actions Get

    Once you have finished learning the basics of how to use the CAS API, you can use this endpoint to learn more about what you can do with the API.

    You can use this command to get a list of all the possible actions per task

    client.CAS.actions.list().then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/cas/actions
    

    example response

    {
        "external": {
            "send_email": {
                "subject": {
                    "required": true,
                    "type": "string",
                    "minlength": 1,
                    "maxlength": 998
                },
                "html": {
                    "type": "string"
                },
                "to": {
                    "required": true,
                    "type": "email"
                },
                "text": {
                    "type": "string"
                }
            },
            "send_slack": {
                "webhook_url": {
                    "required": true,
                    "type": "url"
                },
                "message": {
                    "required": true,
                    "type": "dict"
                }
            },
            "http_request": {
                "url": {
                    "required": true,
                    "type": "url"
                },
                "url_parameters": {
                    "type": "dict"
                },
                "headers": {
                    "type": "dict"
                },
                "data": {
                    "type": "dict"
                },
                "request_type": {
                    "allowed": [
                        "GET",
                        "PUT",
                        "PATCH",
                        "POST",
                        "DELETE"
                    ]
                }
            }
        }
    }
    

    Response

    There are three possible actions per task

    Each action has its own required parameters

    send_email

    Parameter type Description
    subject string required The subject of the email to be sent
    html string The html sent with the body of the email
    to string required The notification receiver (needs to be an email registered on your account)
    text string The text body sent with the email.

    send_slack

    Parameter type Description
    webhook_url url required The slack webhook_url found on your workspace's custom integrations - Learn more about Slack's API here
    message dict required A Key:Value pair like so {"text": "Your message here"}

    http_request

    Parameter type Description
    url string required The url you want to send the request to e.g. https://yourapi.com.
    url_parameters dict Key:Value pair to send in the url of the request
    headers dict Key:Value pair to send in the headers of the request
    data dict Key:Value pair to send in the body of the request only available on POST, PATCH and PUT requests
    request_type string Either: GET, PUT, PATCH, POST or DELETE

    PaaS

    Our Platform Services allow you to create and setup a backend service in no time.

    Platform Services consist of three main endpoints

    endpoint Description
    service_templates Service Templates are a catalog of available services, basically a list of every possible service templates, You can not POST or PATCH this endpoint.
    security_zones When you create a new service, it will be placed in a security zone, you can create new zones and assign your Services to them. By default, a security zone is created when you create your first platform service, If you would like to use another zone you will need to create one yourself here
    services They are the instances of a service template that you create, a GET request returns all PaaS instances you have created.

    Below we will show you how to get start with our Platform Services via the API.

    Services Get

    You can use this command to get a list of your services

    client.PAAS.services.list().then(function( res ) {
        console.log(res.result);
    }); 
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/paas/services
    

    Example response

    {
    "paas_services": {
        "d0dd575a-7b0d-4c8f-a037-1f44ee91542e": {
            "object_uuid": "d0dd575a-7b0d-4c8f-a037-1f44ee91542e",
            "labels": [],
            "service_template_uuid": "504e2d11-7255-4712-b744-fcb093a4e613",
            "create_time": "2018-04-28T09:47:41Z",
            "status": "active",
            "current_price": 5.889236109765,
            "listen_ports": {
                "fcfc::1:305e:6eff:fe62:4503": {
                    "mysql": 3306
                }
            },
            "credentials": [
                {
                    "username": "root",
                    "password": "fW4RS41XU6i2V606ezmP084sPLbi7Zgh",
                    "type": "mysql"
                }
            ],
            "usage_in_minutes": 7269,
            "change_time": "2018-04-30T10:57:53Z",
            "name": "test",
            "security_zone_uuid": "d711fc50-ad96-4070-b769-6fe2bf93792c"
        },
    }
    }
    

    Response

    Parameter type Description
    object_uuid string The unique UUID of the Platform service.
    Labels array An array of strings, labelling your PaaS for better sorting, filtering etc.
    service_template_uuid string The UUID of the service_template that was used to create the service.
    current_price float The current price this service has cost since the last bill.
    listen_ports object{} Contains the IPv6 address and port that the Service will listen to, you can use these details to connect internally to a service.
    listen_ports.IPv6.mysql The key mysql will change depending on the service, The value 3306 is the listening port of the application.
    credentials array{} Contains the initial setup credentials for Service.
    credentials.username string The initial username to authenticate the Service.
    credentials.password string The initial password to authenticate the Service.
    credentials.type string The type of Service.
    usage_in_minutes int Total minutes the service has been running.
    name string The name of the Service.
    security_zone_uuid string The UUID of the security zone that the service is running in.

    Service Get

    You can use this command to get information regarding a specific service

    client.PAAS.services.get(uuid).then(function( res ) {
        console.log(res.result);
    }); 
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/paas/services/{uuid}
    

    Example response

    {
    "paas_service": {
        "object_uuid": "d0dd575a-7b0d-4c8f-a037-1f44ee91542e",
        "labels": [],
        "credentials": [
            {
                "password": "fW4RS41XU6i2V606ezmP084sPLbi7Zgh",
                "username": "root",
                "type": "mysql"
            }
        ],
        "create_time": "2018-04-28T09:47:41Z",
        "listen_ports": {
            "fcfc::1:305e:6eff:fe62:4503": {
                "mysql": 3306
            }
        },
        "security_zone_uuid": "d711fc50-ad96-4070-b769-6fe2bf93792c",
        "service_template_uuid": "504e2d11-7255-4712-b744-fcb093a4e613",
        "usage_in_minutes": 7315,
        "current_price": 5.926504628275,
        "change_time": "2018-04-30T10:57:53Z",
        "status": "active",
        "name": "test"
    }
    }
    

    Response

    Parameter type Description
    object_uuid string The unique UUID of the Platform service.
    labels array An array of strings, labelling your PaaS for better sorting, filtering etc.
    service_template_uuid string The UUID of the service_template that was used to create the service.
    current_price float The current price this service has cost since the last bill.
    listen_ports object{} Contains the IPv6 address and port that the Service will listen to, you can use these details to connect internally to a service.
    listen_ports.IPv6.mysql The key mysql will change depending on the service, The value 3306 is the listening port of the application.
    credentials array{} Contains the initial setup credentials for Service.
    credentials.username string The initial username to authenticate the Service.
    credentials.password string The initial password to authenticate the Service.
    credentials.type string The type of Service.
    usage_in_minutes int Total minutes the service has been running.
    name string The name of the Service.
    security_zone_uuid string The UUID of the security zone that the service is running in.

    Service Create

    You can use this command to create a Platform Service.

    client.PAAS.services.create({"name":"test","paas_service_template_uuid":"43de8cf3-608c-41b7-b4d0-e947887bbac0"}).then(function( res ) { 
        console.log(res.result);
    });
    
    curl -H "Content-type: Application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name":"test","paas_service_template_uuid":"43de8cf3-608c-41b7-b4d0-e947887bbac0"}' \
         -X POST \
         https://api.gridscale.io/objects/paas/services
    

    Example request body

    {
        "name":"test",
        "paas_service_template_uuid":"43de8cf3-608c-41b7-b4d0-e947887bbac0"
    }
    

    Example response

    {
    "request_uuid": "960bb1b8-5336-42c3-a85c-e2344c9abc6e",
    "listen_ports": {
        "fcfc::1:3c70:3bff:fe81:8103": {
            "mysql": 3306
        }
    },
    "paas_service_uuid": "60156647-34ed-4af9-b9cb-6babb61b93b2",
    "credentials": [
        {
            "type": "mysql",
            "username": "root",
            "password": "CgUQ5kXl2qN59095ZPY41S9n210DqjNZ"
        }
    ]
    }
    

    Request

    It only takes two parameters to create a Platform service, you will need to find the UUID of the Service you would like to create with a GET request to the /service_templates endpoint.

    Or

    As of 2018.05.01 the complete list is here

    Parameter type required Description
    name string required The name of the service.
    paas_service_template_uuid string required The template used to create the service, you can find an available list at the /service_templates endpoint.
    labels array Labels to organise your objects.
    paas_security_zone_uuid string The UUID of the security zone you would like to assign this service to.

    Response

    The response returns all the information you need to connect to the service.

    Parameter type Description
    listen_ports object{} Contains the IPv6 address and port that the Service will listen to, you can use these details to connect internally to a service.
    listen_ports.IPv6.mysql The key mysql will change depending on the service, The value 3306 is the listening port of the application.
    paas_service_template_uuid string The UUID of the service_template that was used to create the service.
    credentials array{} Contains the initial setup credentials for Service.
    credentials.username string The initial username to authenticate the Service.
    credentials.password string The initial password to authenticate the Service.
    credentials.type string The type of Service.

    Service Update

    You can use this command to Updated an existing Platform Service.

    client.PAAS.services.patch("b9767fbe-3c0e-4915-b8f1-a26a7c2014cc", {"name":"updatedname"}).then(function( res ) { // done
        console.log(res.success);
    });
    
    curl -H "Content-type: Application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name":"New Name"}' \
         -X PATCH \
         https://api.gridscale.io/objects/paas/services/{service_uuid}
    

    Example request body

    {
        "name":"New Name"
    }
    

    Request

    Once a service has been created, it's service type cannot be changed, we can only update the Name and labels of a service.

    Parameter type required Description
    name string The name of the service.
    labels array The labels for this template

    Response

    A 204 response with an empty body signifies a successful update.

    Service Delete

    You can use this command to Delete an existing Platform Service.

    client.PAAS.services.remove("b9767fbe-3c0e-4915-b8f1-a26a7c2014cc").then(function( res ) { // done
        console.log(res.success);
    });
    
    curl -H "Content-type: Application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE  \
         https://api.gridscale.io/objects/paas/services/{service_uuid}
    

    Response

    A 204 response with an empty body signifies a successful update.

    Service Templates Get

    You can use this command to get a list of available service templates

    client.PAAS.serviceTemplates.list().then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/paas/service_templates
    

    Example response

    {
        "paas_service_templates": {
            "929cafe1-9d77-48e8-8907-698da7b5adb6": {
                "name": "PostgreSQL 64G",
                "object_uuid": "929cafe1-9d77-48e8-8907-698da7b5adb6",
                "category": "database",
                "labels": [],
                "product_no": 1200004,
                "resources": {
                    "memory": 65536,
                    "connections": 500
                },
                "status": "active",
                "parameters_schema": {}
            },
            "30d4df48-99d4-414b-9de7-f16293396a62": {
                "name": "Redis 128M",
                "object_uuid": "30d4df48-99d4-414b-9de7-f16293396a62",
                "category": "key_value_store",
                "labels": [],
                "product_no": 1202002,
                "resources": {
                    "memory": 128,
                    "connections": 100
                },
                "status": "active",
                "parameters_schema": {}
            },
            "b5ba641c-df2c-4de2-9153-64eaa7199c55": {
                "name": "Redis 256M",
                "object_uuid": "b5ba641c-df2c-4de2-9153-64eaa7199c55",
                "category": "key_value_store",
                "labels": [],
                "product_no": 1202003,
                "resources": {
                    "memory": 256,
                    "connections": 200
                },
                "status": "active",
                "parameters_schema": {}
            },
            "4f2b3f74-9596-4f79-88eb-cd0db97b09df": {
                "name": "MySQL 128G",
                "object_uuid": "4f2b3f74-9596-4f79-88eb-cd0db97b09df",
                "category": "database",
                "labels": [],
                "product_no": 1201005,
                "resources": {
                    "memory": 131072,
                    "connections": 500
                },
                "status": "active",
                "parameters_schema": {}
            },
            "504e2d11-7255-4712-b744-fcb093a4e613": {
                "name": "MySQL 1G",
                "object_uuid": "504e2d11-7255-4712-b744-fcb093a4e613",
                "category": "database",
                "labels": [],
                "product_no": 1201001,
                "resources": {
                    "memory": 1024,
                    "connections": 100
                },
                "status": "active",
                "parameters_schema": {}
            },
            "56ffd184-231a-40dc-83da-46a252489854": {
                "name": "Redis 8192M",
                "object_uuid": "56ffd184-231a-40dc-83da-46a252489854",
                "category": "key_value_store",
                "labels": [],
                "product_no": 1202006,
                "resources": {
                    "memory": 8192,
                    "connections": 5000
                },
                "status": "active",
                "parameters_schema": {}
            },
            "06a7e721-fb7d-40f1-89d0-a7588916416e": {
                "name": "PostgreSQL 1G",
                "object_uuid": "06a7e721-fb7d-40f1-89d0-a7588916416e",
                "category": "database",
                "labels": [],
                "product_no": 1200001,
                "resources": {
                    "memory": 1024,
                    "connections": 100
                },
                "status": "active",
                "parameters_schema": {}
            },
            "013ab258-a845-465d-9bd4-92e107d5b6ff": {
                "name": "PostgreSQL 16G",
                "object_uuid": "013ab258-a845-465d-9bd4-92e107d5b6ff",
                "category": "database",
                "labels": [],
                "product_no": 1200003,
                "resources": {
                    "memory": 16384,
                    "connections": 400
                },
                "status": "active",
                "parameters_schema": {}
            },
            "a6ed1984-674d-4fdc-97ac-34e4950ee600": {
                "name": "PostgreSQL 128G",
                "object_uuid": "a6ed1984-674d-4fdc-97ac-34e4950ee600",
                "category": "database",
                "labels": [],
                "product_no": 1200005,
                "resources": {
                    "memory": 131072,
                    "connections": 500
                },
                "status": "active",
                "parameters_schema": {}
            },
            "8550b3ae-f5e8-4af4-9652-f11444e902ba": {
                "name": "MySQL 4G",
                "object_uuid": "8550b3ae-f5e8-4af4-9652-f11444e902ba",
                "category": "database",
                "labels": [],
                "product_no": 1201002,
                "resources": {
                    "memory": 4096,
                    "connections": 200
                },
                "status": "active",
                "parameters_schema": {}
            },
            "b3d39746-9172-4da9-94c4-99bc5923574d": {
                "name": "MySQL 64G",
                "object_uuid": "b3d39746-9172-4da9-94c4-99bc5923574d",
                "category": "database",
                "labels": [],
                "product_no": 1201004,
                "resources": {
                    "memory": 65536,
                    "connections": 500
                },
                "status": "active",
                "parameters_schema": {}
            },
            "f23cbbff-e6e3-4716-8396-75d065183105": {
                "name": "Redis 2048M",
                "object_uuid": "f23cbbff-e6e3-4716-8396-75d065183105",
                "category": "key_value_store",
                "labels": [],
                "product_no": 1202005,
                "resources": {
                    "memory": 2048,
                    "connections": 1600
                },
                "status": "active",
                "parameters_schema": {}
            },
            "8fd7e305-4fb1-4503-98bf-de049f8f7c72": {
                "name": "MySQL 16G",
                "object_uuid": "8fd7e305-4fb1-4503-98bf-de049f8f7c72",
                "category": "database",
                "labels": [],
                "product_no": 1201003,
                "resources": {
                    "memory": 16384,
                    "connections": 400
                },
                "status": "active",
                "parameters_schema": {}
            },
            "22ecec3f-6d8c-43aa-ad2e-f944f9c3837a": {
                "name": "PostgreSQL 4G",
                "object_uuid": "22ecec3f-6d8c-43aa-ad2e-f944f9c3837a",
                "category": "database",
                "labels": [],
                "product_no": 1200002,
                "resources": {
                    "memory": 4096,
                    "connections": 200
                },
                "status": "active",
                "parameters_schema": {}
            },
            "c2c3705d-c09b-474b-83fe-d9693bac17a4": {
                "name": "Redis 64M",
                "object_uuid": "c2c3705d-c09b-474b-83fe-d9693bac17a4",
                "category": "key_value_store",
                "labels": [],
                "product_no": 1202001,
                "resources": {
                    "memory": 64,
                    "connections": 50
                },
                "status": "active",
                "parameters_schema": {}
            },
            "9553a827-fb94-460d-af6d-7078cee59ded": {
                "name": "Redis 8192M (Test)",
                "object_uuid": "9553a827-fb94-460d-af6d-7078cee59ded",
                "category": "key_value_store",
                "labels": [],
                "product_no": 1202006,
                "resources": {
                    "memory": 8192,
                    "connections": 5000
                },
                "status": "active",
                "parameters_schema": {}
            },
            "fe5152a9-49f2-4d08-8844-199d19ccf713": {
                "name": "Redis 512M",
                "object_uuid": "fe5152a9-49f2-4d08-8844-199d19ccf713",
                "category": "key_value_store",
                "labels": [],
                "product_no": 1202004,
                "resources": {
                    "memory": 512,
                    "connections": 400
                },
                "status": "active",
                "parameters_schema": {}
            }
        }
    }
    

    Here is a list of Service Templates that you can use to create a service. You will need the object_uuid when creating a new Service.

    Response

    Parameter type Description
    name string The name of the Service.
    object_uuid string The unique UUID of the Platform service.
    catagory string Describes the catagory of the service.
    resources object The Resources that the service_templates required
    resources.memory int The amount of memory required by the service, either RAM(MB) or SSD Storage(GB)
    resouces.connections int The amount of concurrent connections for the service.

    Security Zones Get

    You can use this code to get a list of Security Zones

    client.PAAS.securityZones.list().then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/paas/security_zones
    

    Example response

    {
        "paas_security_zones": {
            "d711fc50-ad96-4070-b769-6fe2bf93792c": {
                "change_time": "2018-04-28T09:47:41Z",
                "status": "active",
                "create_time": "2018-04-28T09:47:41Z",
                "location_name": "de/fra",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "object_uuid": "d711fc50-ad96-4070-b769-6fe2bf93792c",
                "relations": {
                    "services": []
                },
                "location_country": "de",
                "labels": [],
                "location_iata": "fra",
                "name": "test"
            }
        }
    }
    

    Response

    Parameter type Description
    location_name string The human readable name of the datacenter that this zone belongs to.
    location_uuid string The UUID of the datacenter that this zone belongs to.
    object_uuid string The unique UUID of the Security Zone.
    relations array A list of Services running at this location.
    name string The name of the Security Zone.

    Security Zone Get

    You can use this command to get information regarding a specific security zone.

    client.PAAS.securityZones.get("zone_uuid").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X GET \
         https://api.gridscale.io/objects/paas/security_zones/{paas_security_zone_uuid}
    

    Example response

    {
        "paas_security_zones": {
            "d711fc50-ad96-4070-b769-6fe2bf93792c": {
                "change_time": "2018-04-28T09:47:41Z",
                "status": "active",
                "create_time": "2018-04-28T09:47:41Z",
                "location_name": "de/fra",
                "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950",
                "object_uuid": "d711fc50-ad96-4070-b769-6fe2bf93792c",
                "relations": {
                    "services": []
                },
                "location_country": "de",
                "labels": [],
                "location_iata": "fra",
                "name": "test"
            }
        }
    }
    

    When our Platform Services cover more zones, you can use this endpoint to query a single Security Zone, and your services currently running in the requests Security Zone.

    Response

    Parameter type Description
    location_name string The human readable name of the datacenter that this zone belongs to.
    location_uuid string The UUID of the datacenter that this zone belongs to.
    object_uuid string The unique UUID of the Security Zone.
    relations array A list of Services running at this location.
    name string The name of the Security Zone.

    Security Zone Create

    You can use this command to create a new security zone

    client.PAAS.securityZones.create({"name": "new zone", "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-type: Application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "new zone", "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"}' \
         -X POST \
         https://api.gridscale.io/objects/paas/security_zones
    

    Example response

    {
        "paas_security_zone_uuid": "a1de6e06-3552-4718-a5f2-0073fb269267",
        "request_uuid": "17fe566f-e6af-4e34-89fe-27518d31f7bf"
    }
    

    A security zone essentially works like a network. It connect services that are located within the zone with servers that are connected to the zone. The first security zone will be created by us on demand, and it will then be used by default. If you would like to use another zone, you would have to create it yourself first.

    You need two parameters to create a new zone:

    Request

    Parameter type required Description
    name string required The name you give to the security zone.
    location_uuid string required The UUID of the datacenter that this security zone belongs to.

    Response

    Parameter type Description
    paas_security_zone_uuid string The UUID of the security zone. You can use this to place services in this zone in the future.
    request_uuid string The UUID identifying the request.

    a 202 response with the example body signifies a successful request.

    Security Zone Update

    You can use this command to update an existing security zone

    client.PAAS.securityZones.patch({"name": "new zone", "labels": ["Test Zone"]}).then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "Content-type: Application/json" \
         -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -d '{"name": "new zone", "labels": ["Test Zone"]}' \
         -X PATCH \
         https://api.gridscale.io/objects/paas/security_zones/{paas_security_zone_uuid}
    

    A security zone essentially works as a network. It connect services that are located within the zone with servers that are connected to the zone. The first security zone will be created by us on demand, and it will then be used by default. If you would like to use another zone, you would have to create it yourself first.

    You need two parameters to create a new zone - name and location_uuid the paas_security_zone_uuid is optional, only if you would like to use a zone other than the default.

    Request

    Parameter type Description
    name string The name you give to the security zone.
    location_uuid string The UUID of the datacenter that this security zone belongs to.
    paas_security_zone_uuid string The UUID for the security zone you would like to update.

    Response

    a 204 response with an empty body signifies a successful request.

    Security Zone Delete

    You can use this command to delete an existing security zone

    client.PAAS.securityZones.remove("paas_security_zone_uuid").then(function( res ) {
        console.log(res.result);
    });
    
    curl -H "X-Auth-UserId: ##User_UUID##" \
         -H "X-Auth-Token: ##API-Token##" \
         -X DELETE \
         https://api.gridscale.io/objects/paas/security_zones/{paas_security_zone_uuid}
    

    Response

    a 204 response with an empty body signifies a successful request.