New - Expand example descriptions

API Specification (1.0.1)

Download OpenAPI specification:Download

Introduction

Welcome to gridscale's API documentation.

A REST API is a programming interface that allows you to access and send data directly to our systems 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 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.

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. Meaning we can not guarantee the success of the request. You should poll the request to be notified once the resource has been provisioned - see the requests endpoint on how to poll.
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 taken 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 Parameter Description
Access-Control-Allow-Methods GET, POST, PUT, PATCH, DELETE, OPTIONS Contains all available methods that may be used for queries.
Access-Control-Allow-Credentials true 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 The HTTP headers available for requests.
Access-Control-Allow-Origin * The domain sent by the browser as a source of demand.
Access-Control-Expose-Headers X-Exec-Time, 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 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.

NodeJs Library

We have a JavaScript library for you to use our API with ease.

npm badge

Requests with our NodeJs lib return a little differently. Everything is the same except it allows you to add URL parameters to customize your requests.

To get started click here .

Authentication

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 remains the same, even if the users email address is changed. The API_Token is a randomly generated hash that allows read/write access.

API_Token

Security scheme type: API Key
header parameter name: X-Auth-Token

User_UUID

Security scheme type: API Key
header parameter name: X-Auth-UserId

Examples

NodeJS

// to get started
// read the docs @ https://www.npmjs.com/package/@gs_js_auth/api
var gs_js_auth = require('@gs_js_auth/api').gs_js_auth;
var client = new gs_js_auth.Client("##API_TOKEN##","##USER_UUID##");

Shell Authentication Headers

  -H "X-Auth-UserId: ##USER_UUID##" \
  -H "X-Auth-Token: ##API_TOKEN##" \

Setting Authentication in your Environment variables

export API_TOKEN="##API_TOKEN##" USER_UUID="##USER_UUID##"

Requests

Request Get

https://api.gridscale.io/requests/{request_uuid} To poll our provisioning system to find out what provisioning state a resource is currently in.

Authorizations:
path Parameters
request_uuid
required
string

UUID of the Server.

Responses

200

successful operation

Response Schema: application/json
property name *
object (Request)
202

The request has been accepted, but will run at a later date. Meaning we can not guarantee the success of the request. You should poll the request to be notified once the resource has been provisioned - see the requests endpoint on how to poll.

400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

get /requests/{request_uuid}

Live

https://api.gridscale.io/requests/{request_uuid}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "4e10fb40-47e3-4fd0-aaf3-c16335757f93":
    {
    }
}

Server

Servers Get

Authorizations:

Responses

200

successful operation

Response Schema: application/json
servers
object (ServerIndex)
400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

get /objects/servers

Live

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

Request samples

Copy
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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "servers":
    {
    }
}

Server Post

Authorizations:
Request Body schema: application/json
name
required
string

The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.

cores
required
integer

The number of server cores.

memory
required
integer

The amount of server memory in GB.

location_uuid
required
string

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.

labels
Array of string

List of labels.

status
string

Status indicates the status of the object.

availability_zone
string

Defines which Availability-Zone the Server is placed.

auto_recovery
string

If the server should be auto-started in case of a failure (default=true).

hardware_profile
string
Enum:"default" "nested" "legacy" "cisco_csr" "sophos_utm" "f5_bigip" "q35" "q35_nested"

Specifies the hardware settings for the virtual machine.

Responses

202

The request has been accepted and being processed. Meaning we can only return the outcome of the request once it's finished processing. To get an accurate result, you should poll the request to be notified once the resource has been provisioned - see the requests endpoint on how to poll.

Response Schema: application/json
server_uuid
string <uuid>
object_uuid
string <uuid>
request_uuid
string <uuid>
network_uuids
Array of string <uuid>
storage_uuids
Array of string <uuid>
ipaddr_uuids
Array of string <uuid>
400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

post /objects/servers

Live

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "cores": 1,
  • "memory": 2,
  • "location_uuid": "45ed677b-3702-4b36-be2a-a2eab9827950"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "request_uuid": "x123xx1x-123x-1x12-123x-123xxx123x1x",
  • "object_uuid": "690de890-13c0-4e76-8a01-e10ba8786e53"
}

Server Get

https://api.gridscale.io/objects/servers/{server_uuid} To receive detailed information regarding a specific server.

Authorizations:
path Parameters
server_uuid
required
string

UUID of the Server.

Responses

200

successful operation

Response Schema: application/json
server
object (Server)
400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

get /objects/servers/{server_uuid}

Live

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

Request samples

Copy
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}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "server":
    {
    }
}

Server Patch

Authorizations:
path Parameters
server_uuid
required
string

object that need to be updated.

Request Body schema: application/json
name
string

The human-readable name of the object. It supports the full UTF-8 charset, with a maximum of 64 characters.

cores
integer

The number of server cores.

memory
integer

The amount of server memory in GB.

labels
Array of string

List of labels.

availability_zone
string

Defines which Availability-Zone the Server is placed.

auto_recovery
string

If the server should be auto-started in case of a failure (default=true).

Responses

204

The request was successful, but the answer deliberately contains no data.

400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

patch /objects/servers/{server_uuid}

Live

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Updated Name"
}

Server Delete

Authorizations:
path Parameters
server_uuid
required
string

object that need to be deleted

Responses

204

The request was successful, but the answer deliberately contains no data.

400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

delete /objects/servers/{server_uuid}

Live

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

Request samples

Copy
curl -H "X-Auth-UserId: $USER_UUID" \
    -H "X-Auth-Token: $API_TOKEN" \
    -X DELETE \
    https://api.gridscale.io/objects/servers/{server_uuid}

Server Events

https://api.gridscale.io/objects/servers/{server_uuid}/events Returns the events of a specific server.

Authorizations:
path Parameters
server_uuid
required
string

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.

Responses

200

successful operation

Response Schema: application/json
events
Array of object
400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

get /objects/servers/{server_uuid}/events

Live

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

Request samples

Copy
curl -H "X-Auth-UserId: $USER_UUID" \
    -H "X-Auth-Token: $API_TOKEN" \
    -X GET \
    https://api.gridscale.io/objects/servers/{server_uuid}/events

Response samples

application/json
Copy
Expand all Collapse all
{
  • "events":
    [
    ]
}

Server Usage

Authorizations:
path Parameters
server_uuid
required
string

UUID of the Server.

Responses

200

successful operation

Response Schema: application/json
server_metrics
Array of object (PaasServiceMetricsList)
400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

get /objects/servers/{server_uuid}/metrics

Live

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

Request samples

Copy
curl -H "X-Auth-UserId: $USER_UUID" \
    -H "X-Auth-Token: $API_TOKEN" \
    -X GET \
    https://api.gridscale.io/objects/servers/{server_uuid}/metrics

Response samples

application/json
Copy
Expand all Collapse all
{
  • "server_metrics":
    [
    ]
}

Server Power Status

Server Power Get

https://api.gridscale.io/objects/servers/{server_uuid}/power Returns the Servers current power status.

Authorizations:
path Parameters
server_uuid
required
string

ID of storage

Responses

200

successful operation

Response Schema: application/json
power
boolean

The power status of the server.

400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

get /objects/servers/{server_uuid}/power

Live

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

Request samples

Copy
curl -H "X-Auth-UserId: $USER_UUID" \
    -H "X-Auth-Token: $API_TOKEN" \
    -X GET \
    https://api.gridscale.io/objects/servers/{server_uuid}/power

Response samples

application/json
Copy
Expand all Collapse all
{
  • "power": true
}

Server Power Patch

Authorizations:
path Parameters
server_uuid
required
string

ID of server

Request Body schema: application/json
power
boolean

Power state to set

Responses

200

successful operation

204

The request was successful, but the answer deliberately contains no data.

400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

patch /objects/servers/{server_uuid}/power

Live

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "power": true
}

Server ACPI Shutdown

Authorizations:
path Parameters
server_uuid
required
string

ID of server

Request Body schema: application/json

Responses

204

The request was successful, but the answer deliberately contains no data.

400

Bad request.

401

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

Action can not be executed - not provided any or invalid payment methods.

403

The request was not carried out due to lack of authorization of the user or because an impossible action was requested.

404

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

The request may be made only with other HTTP methods (eg GET rather than POST).

409

The request was made under false assumptions. For example, a user can not be created twice with the same email.

415

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

The request could not be performed because the object is in the wrong status.

500

Internal error: Please contact us to report the issue.

503

The request could not be performed because there was a temporary error on our side. Please try again later.

patch /objects/servers/{server_uuid}/shutdown

Live

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

Request samples

application/json
Copy
Expand all Collapse all
{ }

Server Storages

Server Storages Get

Authorizations:
path Parameters
server_uuid
required
string

ID of server

Responses

<