Introduction

KraftCloud offers a highly performant REST API which is accessible at

https://api.X.kraft.cloud/v1/Y

where X is your metro, and Y is the category of API endpoints (e.g., instances for managing instances). We use fra0 (Frankfurt, DE) as the example metro in this documentation.

To use the KraftCloud REST API, you need to authenticate using an API token. This will be provided to you during your on-boarding. Once you have the token, you include it in your API requests using the Authorization header as follows:

Authorization: Bearer ${KRAFTCLOUD_TOKEN}

API Endpoints

The KraftCloud REST API provides the following categories of endpoints:

Category	Purpose and Description
Autoscale	Manage autoscale settings for your service groups
Certificates	Manage your TLS certificates
Images	Get an overview of available images
Instances	Create new and manage existing Unikraft instances
Services	Publish network services and create load balancing groups
Users	Inspect quota settings and your account’s amount of used resources
Volumes	Create and manage volumes for persistent storage

The endpoints accept parameters via JSON objects in the request body. See the individual endpoint’s section for the available parameters. To prevent misconfigurations, KraftCloud aborts requests that contain unknown, ill-typed, or otherwise invalid parameters. A corresponding error message is included in the response (see API Responses).

Global Scope vs. Local Scope

Many endpoints can be accessed in global scope and in local scope. The global scope allows batch operations by specifying multiple requests for the same endpoint as a JSON array (e.g.,to start or stop multiple instances in a single call). In contrast, the local scope operates on one specific instance only.

Global:

https://api.fra0.kraft.cloud/v1/<category>/<endpoint>

Local:

https://api.fra0.kraft.cloud/v1/<category>/<object>/<endpoint>

Some endpoints such as for creating a new object or getting the status of an object are accessed via the HTTP method: POST or GET on the /<category> or /<category>/<object> URL; they don’t have an explicit <endpoint> component. See the individual endpoint’s documentation for the URLs and HTTP methods available.

Specifying an Object by UUID

KraftCloud refers to objects like instances and service groups using Universally Unique Identifiers (UUID) of the form 7bece402-c36f-457f-a165-0e2d63f1db53. Each object is assigned a random UUID during creation and keeps it until the object is deleted.

Querying the status of multiple instances (global scope):

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/instances" \
     -d '[
        {
           "uuid": "7bece402-c36f-457f-a165-0e2d63f1db53"
        }, {
           "uuid": "d6bb5ad2-402e-4f8d-981d-caf52110426e"
        }
     ]'

Querying the status of only one specific instance (local scope):

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     "https://api.fra0.kraft.cloud/v1/instances/7bece402-c36f-457f-a165-0e2d63f1db53"

If the endpoint does not require any other parameters than the object’s UUID, the JSON request body can be omitted.

Specifying an Object by Name

To simplify working with objects like instances and service groups, KraftCloud supports the ability to set a custom name when you create an object: you can then reference the object from the global scope by name. For example, if the first instance has the name my-instance, you can use the instance’s name instead of its UUID:

curl -X GET \
     -H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
     -H "Content-Type: application/json" \
     "https://api.fra0.kraft.cloud/v1/instances/status" \
     -d '[
        {
           "name": "my-instance"
        }, {
           "uuid": "d6bb5ad2-402e-4f8d-981d-caf52110426e"
        }
     ]'

The object name must be a valid domain name according to RFC 1035:

Labels are not longer than 63 characters, and at least 1 character
Only digits (0-9), letters (a-z, A-Z), hyphens (-), and dots (.) to separate labels are allowed
Labels may only start with a letter
Labels may only end with a letter or digit
Consecutive hyphens and dots are not allowed

In addition, the following restrictions apply:

Upper case letters are converted to lower case
Maximum name length is 121 including label separators
The name must not be a fully-qualified domain name (FQDN) - i.e., it must not end with a dot (.)

API Responses

The API uses standard HTTP response codes to indicate success or failure. In addition, the response body contains more details about the result of the operation in a JSON object. On success the data member contains an array of objects with one object per result. The array is named according to the type of object that the request is operating on. For example, when working with instances the response contains an instances array.

{
  "status": "success",
  "data": {
    "instances": [
      {
        "status": "success",
        "uuid": "7bece402-c36f-457f-a165-0e2d63f1db53"
        ...
      }
    ]
  }
}

{
  "status": "error",
  "errors": [
    {
      "status": 401
    }
  ]
}

Requests may also be partially successful if the operation could be performed for some of the specified objects only:

{
  "status": "partial_success",
  "message": "Failed to perform all operations",
  "data": {
    "instances": [
      {
        "status": "error",
        "uuid": "3b5b4c36-2c9b-46e4-80c6-7e5b561938c3",
        "message": "No instance with UUID '3b5b4c36-2c9b-46e4-80c6-7e5b561938c3'",
        "error": 8
      },
      {
        "status": "success",
        "uuid": "d7354fc2-8ada-4376-b06f-6385cdc460c5",
        ...
      }
    ]
  }
}