Download OpenAPI specification:Download
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.
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. |
| 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. |
| 416 | Requested Range Not Satisfiable |
The request could not be fulfilled. It is possible that a resource limit was reached or an IPv4 address pool is exhausted. |
| 424 | Failed Dependency |
The request could not be performed because the object is in the wrong status. |
| 429 | Too Many Requests |
The request has been rejected because rate limits have been exceeded. |
| Header | Description |
|---|---|
| Content-Type | Always "application/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. |
| Header | Description |
|---|---|
| Content-Type | Always "application/json". |
| X-Time-Provisioning | The time taken to process the request (in ms). |
| X-Api-Identity | The currently active Provisioning API version. Useful when reporting bugs to us. |
| X-Request-Id | The unique identifier of the request, be sure to include it when referring to a request. |
| RateLimit-Limit | The number of requests that can be made per minute. |
| RateLimit-Remaining | The number of requests that still remain before you hit your request limit. |
| RateLimit-Reset | A Unix timestamp in milliseconds of when the rate limit will reset, or the time at which a request no longer will return 429 - Too Many Requests. |
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. |
The number of requests that can be made through our API is currently limited to 72 requests per 60 seconds (roughly one request per second plus a little headroom). The current state of rate limiting is returned within the response headers of each request. The relevant response headers are
See the Response Headers section for details.
As long as the RateLimit-Remaining count is above zero, you will be able to make further requests. As soon as the RateLimit-Remaining header value is zero, subsequent requests will return the 429 status code. This will stay until the timestamp given in RateLimit-Reset has been reached.
HTTP/1.0 429 TOO MANY REQUESTS
Content-Length: 66
Content-Type: application/json; charset=utf-8
Date: Mon, 11 Nov 2019 11:11:33 GMT
RateLimit-Limit: 72
RateLimit-Remaining: 0
RateLimit-Reset: 1573468299256
{
"id": "too_many_requests",
"message": "API Rate limit exceeded."
}It is important to understand how rate limits are reset in order to use the API efficiently. Rate limits are reset for all counted requests at once. This means that that once the timestamp RateLimit-Remaining has arrived all counted request are reset and you can again start sending requests to the API.
This allows for short burst of traffic. The downside is once you have hit the request limit no more requests are allowed until the rate limit duration is reset.
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.
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.
We have a JavaScript library for you to use our API with ease.
Requests with our Node.js 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 .
We also have a Golang library for Gophers.
Requests with our Golang 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 .
We have a Python library, that optionally also simplifies handling of asynchronous requests by mimicking synchronous blocking behaviour.
To get started click here .
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.
Node.js
// 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##");
Golang
// to get started // read the docs @ https://github.com/gridscale/gsclient-go config := gsclient.NewConfiguration( "https://api.gridscale.io", "##USER_UUID##", "##API_TOKEN##", false, //set debug mode ) client := gsclient.NewClient(config)
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##"
https://api.gridscale.io/requests/{request_uuid} To poll our provisioning system to find out what provisioning state a resource is currently in.
| request_uuid required | string UUID of the request. |
successful operation
| property name * | object (Request) |
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.
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
Live
client.watchRequest("4e10fb40-47e3-4fd0-aaf3-c16335757f93").then(function( res ) { console.log(res.result); });
https://api.gridscale.io/objects/servers To retrieve all servers.
successful operation
| servers | object (ServerIndex) |
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
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
https://api.gridscale.io/objects/servers To create a new server.
| 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. |
| 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. |
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.
| 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> |
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
https://api.gridscale.io/objects/servers/{server_uuid} To receive detailed information regarding a specific server.
| server_uuid required | string UUID of the Server. |
successful operation
| server | object (Server) |
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
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}
https://api.gridscale.io/objects/servers/{server_uuid} To update a server.
| server_uuid required | string object that need to be updated. |
| 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). |
The request was successful, but the answer deliberately contains no data.
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
https://api.gridscale.io/objects/servers/{server_uuid} To delete a server.
| server_uuid required | string object that need to be deleted |
The request was successful, but the answer deliberately contains no data.
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
curl -H "X-Auth-UserId: $USER_UUID" \ -H "X-Auth-Token: $API_TOKEN" \ -X DELETE \ https://api.gridscale.io/objects/servers/{server_uuid}
https://api.gridscale.io/objects/servers/{server_uuid}/events Returns the events of a specific server.
| 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. |
successful operation
| events | Array of object |
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
curl -H "X-Auth-UserId: $USER_UUID" \ -H "X-Auth-Token: $API_TOKEN" \ -X GET \ https://api.gridscale.io/objects/servers/{server_uuid}/events
https://api.gridscale.io/objects/servers/{server_uuid}/metrics Returns the usage metrics for the server.
| server_uuid required | string UUID of the Server. |
successful operation
| server_metrics | Array of object (PaasServiceMetricsList) |
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
curl -H "X-Auth-UserId: $USER_UUID" \ -H "X-Auth-Token: $API_TOKEN" \ -X GET \ https://api.gridscale.io/objects/servers/{server_uuid}/metrics
https://api.gridscale.io/objects/servers/{server_uuid}/power Returns the server's current power status.
| server_uuid required | string ID of storage |
successful operation
| power | boolean The power status of the server. |
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.
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.
The request may be made only with other HTTP methods (eg GET rather than POST).
The request was made under false assumptions. For example, a user can not be created twice with the same email.
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.
The request could not be performed because the object is in the wrong status.
The request has been rejected because rate limits have been exceeded.
Internal error: Please contact us to report the issue.
The request could not be performed because there was a temporary error on our side. Please try again later.
Live
curl -H "X-Auth-UserId: $USER_UUID" \ -H "X-Auth-Token: $API_TOKEN" \ -X GET \ https://api.gridscale.io/objects/servers/{server_uuid}/power
https://api.gridscale.io/objects/servers/{server_uuid}/power To turn on and off a server.
| server_uuid required | string ID of server |
| power | boolean Power state to set |
successful operation
The request was successful, but the answer deliberately contains no data.
Bad request.
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.
Action can not be executed - not provided any or invalid payment methods.
The request was not carried out due to lack of authorization of the user or because an impossible action was requested.