Getting started gridscale API

Getting started gridscale API

API gridscale

gridscale API

With the gridscale API you can manage all your servers and resources in the gridscale cloud with a powerful yet easy to use RESTful API. All functions from the Web-Panel GUI and many other expert functions are available, e.g. scaling down storage or hotplug mechanisms.

Here we will give you an overview of the basic functions, API design and all API endpoints.

The complete gridscale API documentation can be found here:

gridscale API Documentation

Request Methods

GETA simple query of information. The answer is given as a JSON object. Requests with GET are always read-only.
POSTCreates new objects and object relations. The POST request must contain all necessary parameters in a JSON object.
PATCHChanges an object or an object relation. The parameters in PATCH requests are usually optional, so that only the changed parameters must be specified in a JSON object.
DELETEDeletes an object or object relation. The object is deleted if it exists. If it does not exist or has already been successfully deleted, a “404 Not Found” is sent.
OPTIONSReturns a list of methods and characteristics supported by the server.

The methods PATCH and DELETE are duplicated – that is, if a request with identical parameters is sent more than once, nothing changes in the result.

HTTP status codes

HTTP statusMessageDescription
200OKThe request has been processed successfully and the result of the request is given in the response.
202AcceptedThe request has been accepted, but will be executed at a later time. The success of the request cannot be guaranteed.
204No ContentThe request was successful, but the response deliberately does not contain any data.
400Bad RequestThe request message had an incorrect structure./td>
401UnauthorizedThe request cannot be executed without valid authentication. X-Auth-UserId or X-Auth-Token HTTP-Header not set or UserID/Token invalid.
402Payment RequiredAction cannot be executed – no or invalid payment methods stored.
403ForbiddenThe request was not executed because the user is not authorized or because an impossible action was requested.
404Not FoundThe requested resource was not found. Also used if a resource exists but the user has no authorization for it.
405Method Not AllowedThe request may only be made using other HTTP methods (for example, GET instead of POST).
409ConflictThe request was made under false assumptions. For example, a user cannot be created twice with the same e-mail.
415Unsupported Media TypeThe content of the request was submitted with invalid or invalid media type. All requests with POST or PATCH must use “Content-Type: application/json” and a JSON object as payload.
424Failed DependencyThe query could not be executed because the object is in the wrong status.

Status 200-204 indicates that the request has been accepted and is being processed (202) or has been (200, 204).

Status 400-424 indicate that there was a problem with the request. You can find more information about the problem in the body of the 4xx answer.

A status 500 means that there was a server-side problem and your request cannot be processed.

HTTP-Request Headers

Content type“application/json”.
X-Auth-UserIdThe user UUID. This can be read out in the panel under “API” and remains the same for a user as long as it exists (e.g. even after changing the user e-mail).
X-Auth-TokenIs a hash generated by the API and must be sent with all API requests. Both the token and its permissions can be configured in the panel.

HTTP-Response Headers

Content type“application/json”.
X-Exec-TimeThe time that provisioning took internally to process the request (in ms)
X-Api-VersionThe currently active Provisioning API version. Useful when reporting bugs to us

Timestamp format

All timestamps follow ISO-8601 and are output in UTC.

CORS – Cross Origin Resource Sharing

To allow API access from other domains, the API supports CORS (Cross Origin Resource Sharing). See also:

This allows JavaScript Web Control Panels running in the browser to use the API directly.

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

Access-Control-Allow-MethodsGET, POST, PUT, PATCH, DELETE, OPTIONSContains all available methods that may be used for queries.
Access-Control-Allow-CredentialstrueIs set to true. Allows the browser to send authentication data via X-Auth HTTP headers.
Access-Control-Allow-HeadersOrigin, X-Requested-With, Content-Type, Accept, X-Auth-UserId, X-Auth-Token , X-Exec-Time, X-Api-VersionThe HTTP headers available for requests.
Access-Control-Allow-Origin*The domain sent by the browser as the source of the request.
Access-Control-Expose-HeadersX-Exec-Time, X-Api-VersionThe HTTP headers that can be used by a browser application.

API Endpoints

For examples of API requests we use cURL. It can be used on most operating systems and enables a simple, clear display of queries in text format.

To test the examples as easily and directly as possible, we use variables as placeholders which you can define as environment variables. So you can try out the examples directly yourself using Copy&Paste:

# in your active Linux terminal or putty window
export X_USERID=your_user_uuid
export X_TOKEN=your_token

Generate your API-Token.


All parameters in POST or PATCH requests must be passed in a JSON object as key-value pairs.

Query available location

With the following command, you can get all server locations available for you.

curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X GET \
     -i \


  "locations": { 
    "39a7d783-3873-4b2f-915b-4c86c28344e5": { 
      "object_uuid": "39a7d783-3873-4b2f-915b-4c86c28344e5", 
      "name": "de/fra", 
      "country": "de", 
      "iata": "fra" 

Create Server

To create a new server, the location (location_uuid) is required in which the server is to be set up. The location cannot be changed later.

curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X POST \
     -d '{"name": "ServerName", "cores":1, "memory":4, "location_uuid":"39a7d783-3873-4b2f-915b-4c86c28344e5"}' \
     -i \

API Response


The response contains the “object_uuid” of the created server and can be used in further requests, for example to request information about the server that has just been created via GET.

curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X GET \
     -i \


Our API is self-descriptive – for each endpoint you can use the HTTP OPTIONS method to get an overview of the possible actions, parameters, request and response values. You can use this information in your automation tools, for example.

Queries with OPTIONS do not require authentication.

curl -X OPTIONS \
     -i \


  • Endpoint collection:

Returns a list of all available API endpoints.

/The API root
/pricesOverview of current resource prices
/objects/locationsList of locations
/objects/locations//serversList servers available in location
/objects/locations//storagesList storages available in location
/objects/locations//networksList networks available in location
/objects/locations//ipsList ips available in location
/objects/locations//templatesList of templates available in location
/objects/storagesActions for storages
/objects/storages//eventsEvents for a storage
/objects/storages//snapshotsActions for snapshots of a storage
/objects/storages//rollbackActions for snapshot rollback of a storage
/objects/networksActions for networks
/objects/networks//eventsEvents for a network
/objects/serversActions for servers
/objects/servers//eventsEvents for a server
/objects/servers//powerPower-Actions for server
/objects/servers//storagesActions for server-storage relations
/objects/servers//networksActions for server-network relations
/objects/servers//ipsActions for server-ip relations
/objects/servers//isoimagesActions for server-isoimage relations
/objects/servers//distanceActions for near/far distance relations
/objects/isoimagesActions for isoimages
/objects/isoimages//eventsEvents for an isoimage
/objects/ipsActions for ips
/objects/ips//eventsEvents for an ip
/objects/templatesActions for templates
/objects/templates//eventsEvents for a template
/objects/sshkeysActions for SSH keys
/objects/sshkeys//eventsEvents for a sshkey
/objects/deleted/serversActions for deleted servers
/objects/deleted/storagesActions for deleted storages
/objects/deleted/networksActions for deleted networks
/objects/deleted/snapshotsActions for deleted snapshots
/objects/deleted/templatesActions for deleted templates
/objects/deleted/isoimagesActions for deleted isoimages
/objects/deleted/ipsActions for deleted ips
/objects/locations/Infos about a location
/objects/storages/Actions for a storage
/objects/storages//snapshots/Actions for a snapshot
/objects/networks/Actions for a network
/objects/servers/Actions for a server
/objects/servers//storages/Actions for a server-storage relation
/objects/servers//networks/Actions for a server-network relation
/objects/servers//ips/Actions for a server-ip relation
/objects/servers//distance/Actions for a near/far distance relation
/objects/ips/Actions for an ip
/objects/templates/Actions for a template
/objects/sshkeys/Actions for a SSH key


  • Endpoint collection:
  • Endpoint object:


object_uuidstringserver uuid
namestringname of the server
labelsobjectlist of labels – each label is a string
coresintegernumber of cores
memoryintegeramount of memory in GiB
statusstringcurrent status of the server
powerbooleanpower status of the server (on: true, off: false)
create_timedatetimeISO 8601 combined date and time in UTC
change_timedatetimeISO 8601 combined date and time in UTC
location_uuidstringlocation uuid
location_namestringname of the location
location_countrystringISO 3166-2 country code
location_iatastringIATA airport code – location identifier
console_tokenstringconsole token for this servers local console (via websocket)
current_pricefloatcurrent object price for the current period since the last billing time
relationsobjectlist of relations to and from this server (siehe: “relations” unter dieser Tabelle)


The relations in the server object serve your comfort – we have already summarized all information for you in such a way that you have a complete overview of your server. All relations can also be queried via their own API endpoints and contain identical data both here and there.

The following relations are described in the server object:

  • distance
  • isoimages
  • storages
  • public_ips
  • networks


Create a new server.


ParameterData typeOptional


AttributData typeDescription
object_uuidstring | UUID of the new Server



curl -H "Content-Type: application/json" \
     -H "X-Auth-UserId: $X_USERID" \
     -H "X-Auth-Token: $X_TOKEN" \
     -X POST \
     -d '{"name": "ServerName", "cores":1, "memory":4, "location_uuid":"39a7d783-3873-4b2f-915b-4c86c28344e5"}' \
     -i \


{"object_uuid": "738aa5e3-b1f5-43df-a77b-085c1a6367f7"}
Zurück zur Tutorial Übersicht Back to Tutorial Overview

gridscale API With the gridscale API you can manage all your servers and resources in the gridscale cloud with a powerful yet easy to use RESTful API. All functions from the Web-Panel GUI and many other expert functions are available, e.g. scaling down storage or hotplug mechanisms. Here we will give you an overview of […]

Schade, dass dir der Artikel nicht gefallen hat.
Was sollten wir deiner Meinung nach besser machen?

Vielen Dank für dein Feedback!
Wir melden uns bei dir, sobald der Artikel zu deinem Wunschthema fertig ist.

Übrigens: kennst du schon unser Tutorial zum Thema The gridscale 1-Click Plesk Template?