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": "ARC-IS-HAF-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.

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

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