Getting StartedIntroductionEndpointsAuthenticationAPI RequestsAPI ResponsesError MessagesPaginationRate LimitingExamplesImagesInstancesSSH KeysSecurity GroupsSnapshotsVolumes

Introduction

Welcome to the Genesis Cloud API documentation.

The Genesis Cloud API provides the ability to manage each services resources programmatically from other scripts or applications without the need to use the graphical Genesis Cloud account dashboard.

The Compute API allows you to manage your Compute Service resources:

  • Instances
  • Security Groups
  • Snapshots
  • Volumes
  • SSH keys and more.

APIs for other services will follow.

The API is also documented as an OpenAPI specification.

Endpoints

Genesis Cloud APIs can be reached via api.genesiscloud.com. Each endpoint follows the following pattern: https://api.genesiscloud.com/{service}/{version}.

Authentication

Each request made to Genesis Cloud APIs must be authenticated. Genesis Cloud APIs handle this with a `X-Auth-Token` HTTP header that must be provided with the request. You can generate an API Key token by visiting the Keys and Tokens section of the Genesis Cloud account dashboard.

Please Note: It is absolutely essential that you keep your secret token private as it provides access to everything in your Genesis Cloud account. If you accidentially publish your secret token, please immiedately revoke it.

TOKEN=xxxxxxxxxxxxxxxxx
curl -H "X-Auth-Token: $TOKEN" \
https://api.genesiscloud.com/compute/v1/instances

API Requests

Genesis Cloud API requests can be performed by any script, software or application that is capable of HTTP requests. An API request consists of the URI representing a resource or a collection of resources and an HTTP verb that indicated what kind of action should be performed on this resource, e.g. describe, create, delete, or update.

HTTP verbAction
GETTo retrieve information about a single resource or a collection of resources use the GET verb. The returned JSON object contains the resource's information.
POSTTo create a new resource use the POST verb. Most POST APIs require that your request contains a JSON object with the parameters needed to create the resource.
DELETETo delete an existing resource use the DELETE verb.
PUTTo update an existing resource use the PUT verb. Most PUT APIs require that your request contains a JSON with the parameters to be updated.
PATCHTo update only a specific property of an existing resource use the PATCH verb. Only the property provided in the JSON parameters will be changed. (Please note when patching a list property with the aim to add one more item, you must provide a list of all items, old plus the new one).

API Responses

HTTP Status

We use conventional HTTP response codes to indicate success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter is missing), and codes in the 5xx range indicate an error with our servers.

HTTP Status Code Summary

  • 200 OK - Everything worked as expected.
  • 201 Created - A new resource was created.
  • 204 No Content - Everything worked and the response does not contain a body.
  • 400 Bad Request - Often missing a required parameter.
  • 401 Unauthorized - No valid API Key provided.
  • 403 Forbidden - Insufficient privileges to access requested resource.
  • 404 Not Found - The requested resource does not exist.
  • 429 Too many requests - You made too many request too quickly.
  • 50x Server errors - Something went wrong on our side.

Most non-2xx status codes are provided with a message in the body giving more detail about the cause of the issue.

Response JSON

Every successful GET request will return JSON object describing either a single resource or a collection of resources. For example GET /compute/v1/instances/<instance_id> will return a JSON object describing the instance with id instance_id :

{
"id": "<instance_id>",
"name": "<name>",
"hostname": "<hostname>",
"type": "vcpu-4_memory-12g_disk-80g_nvidia1080ti-1",
...
"status": "active",
"private_ip": "192.168.10.145",
"public_ip": "194.61.21.92",
"created_at": "2020-03-18T16:25:45.883Z",
"updated_at": "2020-03-18T16:26:38.938Z"
}

Requesting a collection of instances, e.g. GET /compute/v1/instances will return a JSON object containing a list of instances:

{
"instances": [
{
"id": ...
...
},
{
"id": ...
...
}
]
}

Error Messages

Genesis Cloud API error messages are returned in JSON. For example, an error might look like this:

Authentication errors:

{
"code": "01204",
"message": "permission denied"
}

Validation errors:

{
"code": "02010",
"message": "\"hostname\" is required"
}

Error Codes

In addition to descriptive error text, error messages contain machine-parseable codes. While the text for an error message may change, the codes will stay the same.

The following table describes the codes which may appear when working with the standard API (note that the Ads API and some other resource families may present additional error codes). If an error response is not listed in the table, a fallback to the HTTP status codes is required in order to determine the best way to address the issue.

CodeDescription
01204Permission denied
02001Invalid route
02002Malformed request
02003Required fields for body request validation
02004Bad request
02005Invalid ssh key
02006Invalid image
02007Invalid security group
02008Instance not found
02009Request not allowed
02010Max GPU quota reached
02011Snapshot already being created
02012Max instance snapshot quota reached
02013Attempted to delete a non-active instance
02014Authorization token not provided
02015Snapshot not found
02016Snapshot cannot be deleted
02017Legacy large disk instances types are currently not supported
02018Weak password provided - at least 16 chars containing uppercase, lowercase and digits
02019Payment method is required
02020Instance type must be one of (Check instance types list)
02021Volume not found
02022Volumes attached to instances cannot be deleted
02023Only active instances can be updated
02024Default security groups cannot be updated/deleted
02025Security group not foumd
02026Security group is locked for update and delete
02027Security groups used by instances cannot be deleted
02028At least one of the provided security group rules is invalid
02029Instance is already started
02030At least one of the provided security groups cannot be attached
02031At least one of the provided security groups cannot be detached
02032At least one of the provided volumes cannot be attached
02033At least one of the provided volumes cannot be detached
02034Instance cannot be updated
02035The selected image cannot be run on this instance
02036The requested instance configuration is temporarily out of stock

Pagination

Most of the listing requests receive a paginated response, for example getting a list of all your instances. Paginated means that the list is split up into multiple pages each containing at maximum a fixed number of items. Pagination allows dealing with large number of list items via the API.

Paginated request

Requests against paginated endpoints accept two query arguments:

  • per_page Integer Optional - A positive integer lower or equal to 100 to select the number of items to return (default: 50)
  • page Integer Optional - A positive integer to choose the page to return

Paginated endpoints usually also accept filters to search and sort results. These filters are documented along each endpoint documentation.

Paginated response

% curl -H 'X-Auth-Token: <token>' 'https://api.genesiscloud.com/compute/v1/images?page=2&per_page=5' -i
HTTP/1.0 200 OK
{
"data": [
{
...
}
],
"page": 2,
"per_page": 5,
"total_count": 6
}

Rate Limiting

To ensure our platform remains stable, all Genesis Cloud APIs are rate-limited. We use a variety of strategies to enforce rate limits. We ask developers to use industry standard techniques for limiting calls, caching results, and re-trying requests responsibly.

The Genesis Cloud API rate limit window duration is 2 seconds, meaning that a Developer can do 20 requests every 2 seconds.

If the rate limit is exceeded a HTTP 429 response code will be returned and the requested function will not be executed on the server.