Skip to content

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:

CategoryPurpose and Description
AutoscaleManage autoscale settings for your service groups
ImagesGet an overview of available images
InstancesCreate new and manage existing Unikraft instances
ServicesPublish network services and create load balancing groups
UsersInspect quota settings and your account’s amount of used resources
VolumesCreate 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: 200 OK
{
"status": "success",
"data": {
"instances": [
{
"status": "success",
"uuid": "7bece402-c36f-457f-a165-0e2d63f1db53"
...
}
]
}
}
Status: 401 Unauthorized
{
"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: 200 OK
{
"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",
...
}
]
}
}