Skip to main content

Getting Started

The compute API provides the ability to manage each compute resources programmatically from scripts or applications without the need to use the console dashboard.

Endpoints

EpiLayer APIs can be reached via https://public-api.krs-1.epilayer.eu. Each endpoint follows the following pattern:

https://public-api.krs-1.epilayer.eu/{service}/{version}

Compute API​

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

  • Instances
  • Images
  • Snapshots
  • Volumes
  • SSH keys
  • Security Groups
  • Kubernetes Clusters
  • Private Networks
  • Load Balancers

A OpenAPI specification is available at https://public-api.krs-1.epilayer.eu/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://public-api.krs-1.epilayer.eu/compute/v1

restish gc list-instances
restish gc create-instance -h

APIs for other services will follow.

Authentication​

Each request made to EpiLayer APIs must be authenticated. This is done using the Authorization HTTP header that must be provided with each request.

You can generate an API token by visiting the Access Tokens section of the dashboard for your project.

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

TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "Authorization: Bearer $TOKEN" \
  https://public-api.krs-1.epilayer.eu/compute/v1/instances

API Requests​

EpiLayer 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​

EpiLayer 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": "10004",
  "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
10000Internal error
10001Attempted to patch immutable field
10002Pagination expired, restart from the top
10003Conflicting updates, please retry
10004Missing required field
10005Not authenticated for this project
10101Invalid project id
10102Project does not exist
10103Project already exists
10201Invalid ssh key id
10202SSH key does not exist
10203SSH key already exists
10205SSH key in use
10301Invalid network id
10302Network does not exist
10303Network already exists
10305Network in use
10320Network has no CIDR
10401Invalid instance id
10402Instance does not exist
10403Instance already exists
10420Boot image and volume given for instance
10421Instance has no boot source
10422Cannot set delegated ipv6 prefix without base prefix
10423Invalid ipv6 prefix
10424Both raw user-data and high-level user-data info given
10425Raw user data is not valid base64
10426User data maximum length exceeded
10427Requested placement is currently full
10428Requested accelerator configuration is unsupported
10429Placement does not exist
10430Hostname is not valid
10431Requested instance action conflict
10501Invalid security group id
10502Security group does not exist
10503Security group already exists
10505Security group in use
10520Security group rule is invalid
10601Invalid floating ip id
10602Floating ip does not exist
10603Floating ip already exists
10605Floating ip in use
10701Invalid volume id
10702Volume does not exist
10703Volume already exists
10704Volume not ready
10705Volume in use
10721Volume needs either size or source
10722Cannot shrink volume
10723Cannot create a clone that is smaller than its source
10724Both snapshot and boot image given
10801Invalid snapshot id
10802Snapshot does not exist
10803Snapshot already exists
10804Snapshot not ready
10805Snapshot in use
11201Invalid k8s cluster id
11202K8s cluster does not exist
11203K8s cluster already exists
11401Invalid loadbalancer id
11402Loadbalancer does not exist
11403Loadbalancer already exists
11420Loadbalancer has no ports
11421Loadbalancer target is not a valid IP address
11422Loadbalancer target is not in the network CIDR
20220Parsing ssh key failed (Warning)

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://public-api.krs-1.epilayer.eu/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 EpiLayer 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 EpiLayer 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.