Skip to main content

Introduction

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.

Endpoints

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

https://api.genesiscloud.com/{service}/{version}

Compute API​

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

  • Instances
  • Images
  • Snapshots
  • Volumes
  • Filesystems
  • 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 Authorization 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.

Authentication​

Each request made to Genesis Cloud APIs must be authenticated. This is done using the Authorization HTTP header that must be provided with each request. The X-Auth-Token authentication header is now deprecated.

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.

TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "Authorization: Bearer $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.

  • GET To retrieve information about a single resource or a collection of resources use the GET verb. The returned JSON object contains the resource's information.

  • POST To 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.

  • DELETE To delete an existing resource use the DELETE verb.

  • PUT To update an existing resource use the PUT verb. Most PUT APIs require that your request contains a JSON with the parameters to be updated.

  • PATCH To update only a specific property of an existing resource use the PATCH verb. 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).

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.
  • 5xx Server Error 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_nvidia3080-1",
  "region": "NORD-NO-KRS-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-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.

CodeDescription
02001Invalid route
02002Malformed request
02003Missing parameters
02004Bad request
02005Invalid ssh key
02006Invalid image
02007Invalid security group
02008Instance not found
02009Not allowed
02010Max quota reached
02011Snapshot already being created
02012Max instance snapshots quota reached
02013Only active instances can be deleted
02014Auth token not provided
02015Snapshot not found
02016Snapshot cannot be deleted while in use
02017Legacy large disk instances types are currently not supported
02018Weak password
02019Payment method required
02020Instance config (type and/or region) is not allowed
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 found
02026Security group is locked for update and delete
02027Security groups used by instances cannot be deleted
02028At least one of the provided 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
02037Only active instances can be snapshotted
02038The instance is termination protected
02039The instance cannot be started
02040Your account is suspended
02041Your account is banned
02042Your account is disabled
02043Permission denied
02044Genesis Cloud public api is currently disabled. Please visit for more information
02045On-demand billing is not allowed with this instance type
02046Volume is locked, cannot be attached/detached
02047SSH key not found
02048SSH key is improperly formatted
02049Max static public ip quota reached
02050Account not verified
02051Regions mismatch (check <dynamic error source>)
02052Invalid placement option
02053Provided private key
02054Volume type unavailable

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, max: 100)
  • 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 example response

curl -H "Authorization: Bearer $TOKEN" -i \
  "https://api.genesiscloud.com/compute/v1/images?page=2&per_page=5"

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 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.