Using the API

Available APIs

STACKIT Edge Cloud can be operated in a fully automated manner, by using the provided APIs. Different APIs exist depending on the scope of the operation you want to perform:

• The STACKIT Edge Cloud Instance API is a REST API that allows you to create and manage STEC instances.
• You use the Kubernetes REST API to manage STEC resources in your STEC instance.
• You use the Kubernetes REST API and—optionally—Talos Linux gRPC API, to operate edge clusters managed by STACKIT Edge Cloud.

A STEC instance is a control plane running inside of the STACKIT Cloud. It is used to manage STEC components, such as your edge clusters, which are represented as custom resources. We leverage those Kubernetes native objects so you can use the native Kubernetes REST API to manage your edge clusters. However, the permissions you get on the central STEC instance are limited to those custom resources. You won’t be able to deploy workloads on those Kubernetes clusters. Workloads are supposed to be put on the edge clusters you deploy as part of a STEC deployment.

Using the instance API

Authentication

To use the Instance API, you have to authenticate using an authentication method supported by the STACKIT platform. Please review the authentication documentation regarding platform authentication for details.

API documentation

The STACKIT Edge Cloud Instance API is fully documented in a OpenAPI specification.

Example usage

This example will use cURL to demonstrate the use of the Instance API:

> INSTANCE_REGION="eu01"
> PROJECT_ID="12345678-ffff-abcd-ffff-12345678"
> INSTANCE_ID="87654321-abcd-ffff-abcd-87654321"

> curl --request GET \
 --url https://edge.api.stackit.cloud/v1alpha1/projects/$PROJECT_ID/regions/$INSTANCE_REGION/instances/$INSTANCE_ID \
 --header 'Authorization: Bearer <<TOKEN>>'
{
 "created": "2025-08-27T14:51:58Z",
 "description": "My first STEC instance",
 "displayName": "foobar",
 "frontendUrl": "https://app.foobar-3714d85.edge.eu01.stackit.cloud",
 "id": "foobar-3714d85",
 "planId": "87654321-ffff-abcd-ffff-87654321",
 "status": "active"
}

Using the Kubernetes API

Once you have your own STEC instance, every aspect of it is controlled using the Kubernetes API. This is because STEC is fully invested in Kubernetes, so we naturally use it to provide API-primitives to our users. At the end of the day, every host, cluster, and image is a custom resource that is reconciled by the EMP operator. Besides kubectl, or any other Kubernetes client, you won’t need anything to interact with the API.

Authentication

To use the Kubernetes API of your STEC instance, you have to use an authentication method supported by the STACKIT Edge Cloud product. Please review the authentication documentation regarding the product authentication for details.

API documentation

Resource types

There are a few key resources you need to know about when you want to work with STEC. These include EdgeCluster, EdgeMachine and EdgeHost:

• EdgeCluster: the central resource used to manage a Kubernetes cluster and its members.
• EdgeMachine: the intermediary resource between EdgeCluster and EdgeHost. Every host in a cluster has a EdgeMachine resource associated with it.
• EdgeHost: the EdgeHost resource is created when a host is booted from a EdgeImage and successfully registers with the STEC instance.
• EdgeImage: the configuration data of a STEC image that can be used to obtain a boot medium.

EdgeCluster and EdgeImage are the only resources STEC users are supposed to directly interact with (create, update, delete). The EdgeHost can be deleted if no longer in use. All other resources are managed exclusively by controllers, as part of the EMP operator. Don’t try to change managed resources such as EdgeHost or EdgeMachine directly, as any changes will be overwritten by either the EdgeHostLet agent running on the target system (EdgeHost), or the EdgeMachine controller. All changes to the machine config should be done on the EdgeCluster resource.

Resource specifications

Since STEC is using Kubernetes resources to manage clusters, the resource specifications are built in and always up-to-date. To get to know the different aspects of these custom resource definitions, simply use kubectl explain:

> kubectl explain edgeclusters.edge.stackit.cloud.spec
GROUP: edge.stackit.cloud
KIND: EdgeCluster
VERSION: v1alpha1
FIELD: spec <Object>
DESCRIPTION:
 EdgeClusterSpec defines the desired state of EdgeCluster
FIELDS:
 maintenance <Object>
 Configure how maintenance is handled on the given cluster
 nodes <[]Object> -required-
 The nodes that take part in this cluster
 proxy <Object>
 A global proxy tunnel configuration for this cluster
 talos <Object> -required-
 Desired Talos-specific configuration settings

Example usage

You can use any Kubernetes API compatible client to interact with your STEC instance resources. Since the Kubernetes API is also a REST API, any HTTP client can be used too. You can find examples on how to interact with the Kubernetes API in the creating clusters documentation of this user guide.