Welcome to the Genesis Cloud API documentation.
The Genesis Cloud API provides the ability to manage each services resources programmatically from scripts or applications without the need to use the console dashboard.
Genesis Cloud APIs can be reached via
https://api.genesiscloud.com. Each endpoint follows the following pattern:
The Compute API allows you to manage your Compute Service resources:
- SSH keys
- Security Groups
A OpenAPI specification is available at
https://api.genesiscloud.com/compute/v1/openapi.yaml and is compatible with most tooling like OpenAPI generators.
The api can also be used with automated cli tools like Restish:
# make sure to also add the X-Auth-Token header see below
restish api configure gc https://api.genesiscloud.com/compute/v1
restish gc list-instances
restish gc create-instance -h
APIs for other services will follow.
Each request made to Genesis Cloud APIs must be authenticated.
This is done using the
X-Auth-Token HTTP header that must be provided with each request.
You can generate an API token by visiting the Keys and Tokens section of the 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 accidentally publish your token, please immediately revoke it.
curl -H "X-Auth-Token: $TOKEN" \
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.
GETTo retrieve information about a single resource or a collection of resources use the
GETverb. The returned JSON object contains the resource's information.
POSTTo create a new resource use the
POSTverb. 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
PUTTo update an existing resource use the
PUTverb. 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
PATCHverb. Only the properties 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).
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 OKEverything worked as expected.
201 CreatedA new resource was created.
204 No ContentEverything worked and the response does not contain a body.
400 Bad RequestOften missing a required parameter.
401 UnauthorizedNo valid API Key provided.
403 ForbiddenInsufficient privileges to access requested resource.
404 Not FoundThe requested resource does not exist.
429 Too Many RequestsYou made too many request too quickly.
5xx Server ErrorSomething 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.
GET request will return JSON object describing either a single resource or a collection of resources.
GET /compute/v1/instances/<instance_id> will return a JSON object describing the instance with id
Requesting a collection of instances, e.g.
GET /compute/v1/instances will return a JSON object containing a list of instances:
Genesis Cloud API error messages are returned in JSON. For example, an error might look like this:
"message": "permission denied"
"message": "\"hostname\" is required"
In addition to descriptive error text, error messages contain machine-parsable 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.
|Invalid ssh key|
|Invalid security group|
|Instance not found|
|Max quota reached|
|Snapshot already being created|
|Max instance snapshots quota reached|
|Only active instances can be deleted|
|Auth token not provided|
|Snapshot not found|
|Snapshot cannot be deleted while in use|
|Legacy large disk instances types are currently not supported|
|Payment method required|
|Instance config (type and/or region) is not allowed|
|Volume not found|
|Volumes attached to instances cannot be deleted|
|Only active instances can be updated|
|Default security groups cannot be updated/deleted|
|Security group not found|
|Security group is locked for update and delete|
|Security groups used by instances cannot be deleted|
|At least one of the provided rules is invalid|
|Instance is already started|
|At least one of the provided security groups cannot be attached|
|At least one of the provided security groups cannot be detached|
|At least one of the provided volumes cannot be attached|
|At least one of the provided volumes cannot be detached|
|Instance cannot be updated|
|The selected image cannot be run on this instance|
|The requested instance configuration is temporarily out of stock|
|Only active instances can be snapshotted|
|The instance is termination protected|
|The instance cannot be started|
|Your account is suspended|
|Your account is banned|
|Your account is disabled|
|Genesis Cloud public api is currently disabled. Please visit for more information|
|On-demand billing is not allowed with this instance type|
|Volume is locked, cannot be attached/detached|
|SSH key not found|
|SSH key is improperly formatted|
|Max static public ip quota reached|
|Account not verified|
|Regions mismatch (check |
|Invalid placement option|
|Provided private key|
|Volume type unavailable|
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.
Requests against paginated endpoints accept two query arguments:
per_pageInteger Optional - A positive integer lower or equal to 100 to select the number of items to return (default: 50, max: 100)
pageInteger 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 example response
curl -H "X-Auth-Token: $TOKEN" -i \
HTTP/1.0 200 OK
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 allows on average 10 requests per second.
If the rate limit is exceeded a
429 Too Many Requests response code will be returned and the request will not be processed.
Legacy Projects and Accounts
In this documentation there are some exceptions and specific handling for legacy projects and legacy accounts.
Currently all accounts and projects are considered "legacy".