Create and manage links

A Telemetry Link requires an existing Telemetry Router. One Telemetry Link can be created per region for each level (project, folder, organization). Configuring a Telemetry Link requires both the ID and an access token of the Telemetry Router that is to be linked. A Telemetry Link strictly assumes that the configured Telemetry Router is located in the same region.

Prerequisites

• You have a Telemetry Router instance Create and manage instances

API Prerequisites & Variables

To execute the API commands in this guide, you must first export the relevant path parameters as environment variables in your terminal (or replace them directly in the commands). Depending on the hierarchical level of your link, you will need:

• $REGION_ID: The region where your instance is located (e.g., eu01 or eu02).
• $PROJECT_ID: Your STACKIT project ID (if managing a project-level link).
• $FOLDER_ID: Your STACKIT folder ID (if managing a folder-level link).
• $ORGANIZATION_ID: Your STACKIT organization ID (if managing an organization-level link).

If you need help locating these identifiers or want to learn how the stackit curl wrapper works, refer to our central guide: Interacting with the Telemetry Router API.

For a conceptual overview of the different authentication paths, see our Authentication Overview.

Hierarchy of telemetry links

Telemetry links are organized in three levels:

• folders: Captures everything related to folders itself
• organizations: Captures everything related to organizations itself
• projects: Captures everything related to projects and all data within. The vast majority of data runs over this link.

A telemetry link captures data according to its associated level only. There is no inheritance – to capture all available information, you need at least one telemetry link for each level.

Body scheme

Choose the properties for your new or edited link

To create or edit a telemetry link you need to define its parameters. All parameters are part of a JSON config body object of this form:

Body parameter	Meaning	Example
accessToken	The individual access token of your Telemetry Router	eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6ImE1NTZmYWI0MWY2YzQ1MGY3ZDU5YzRmNGVkNWI0NmMxIn0.eyJub3RpY2UiOiJDb25ncmF0dWxhdGlvbnMhIFlvdSBoYXZlIGRlY29kZWQgYSBiZWFyZXIgdG9rZW4gbWVhbnQgZm9yIGRlbW9uc3RyYXRpb24gcHVycG9zZXMuIFdlIGF0IFNUQUNLSVQgZW1waGFzaXplIHNlY3VyaXR5IGFuZCBkYXRhIGludGVncml0eS4gUGxlYXNlIHVzZSB5b3VyIG93biBhY2Nlc3MgdG9rZW4gZm9yIHlvdXIgcmVzb3VyY2VzLiJ9.LPOHfT45JNOpTSh_q6x4pDRVK052QwUwSFU9tLPB6gGrYjf4dTKjWJ-2aRdd2LlWsxO5y0it89VsZpbzVRvI5Q
telemetryRouterId	The ID of your Telemetry Router instance	d5b5cdcc-c155-4d66-82ef-4289db8e4557
enabled	Whether the link should be enabled or not (boolean)	true
displayName	A name for the destination	my-telemetry-link
description	An optional description for your reference	My new telemetry link

For creating, all parameters except description are mandatory. For editing all parameters are optional.

In this context, the accessToken parameter refers to the access token of your Telemetry Router instance and not of your service account.

{
    "accessToken": "<ACCESS_TOKEN>",
    "telemetryRouterId": "<TELEMETRY_ROUTER_ID>",
    "enabled": <ENABLED>,
    "displayName": "<DISPLAY_NAME>",
    "description": "<DESCRIPTION>"
}

Create a link

STACKIT API

To create a telemetry link, you need to call the appropriate endpoint. Each level (folders, organizations and projects) has its own endpoint. The body scheme is equal of each level.

Folder level

stackit curl -X PUT \
"https://telemetry-link.api.stackit.cloud/v1/folders/$FOLDER_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json" \
--data '{
    "accessToken": "<ACCESS_TOKEN>",
    "telemetryRouterId": "<TELEMETRY_ROUTER_ID>",
    "enabled": true,
    "displayName": "<DISPLAY_NAME>",
    "description": "<DESCRIPTION>"
}'

Organization level

stackit curl -X PUT \
"https://telemetry-link.api.stackit.cloud/v1/organizations/$ORGANIZATION_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json" \
--data '{
    "accessToken": "<ACCESS_TOKEN>",
    "telemetryRouterId": "<TELEMETRY_ROUTER_ID>",
    "enabled": true,
    "displayName": "<DISPLAY_NAME>",
    "description": "<DESCRIPTION>"
}'

Project level

stackit curl -X PUT \
"https://telemetry-link.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json" \
--data '{
    "accessToken": "<ACCESS_TOKEN>",
    "telemetryRouterId": "<TELEMETRY_ROUTER_ID>",
    "enabled": true,
    "displayName": "<DISPLAY_NAME>",
    "description": "<DESCRIPTION>"
}'

STACKIT Portal

You can only create one Telemetry Link on each level. With the STACKIT Portal you can furthermore only create Telemetry Links on a project level.

1. On the sidebar, click on Telemetry Link.

2. Click on Create Telemetry Link to create a new link.

   If there already is an entry, you can not create a second one. You either need to delete the existing entry to be able to create a new one or edit it, if you want to make minor changes to it.

3. On the new pane enter the needed information.

   Among the name and an optional description, you are asked for the Telemetry Router ID and its Access token. Refer to Create and manage instances of Telemetry Router and Create and manage access tokens of Telemetry Router on how-to get this information.

4. Click on Create.

View a link

STACKIT API

To view a telemetry link, you need to call the appropriate endpoint. Each level (folders, organizations and projects) has its own endpoint.

Folder level

stackit curl -X GET \
"https://telemetry-link.api.stackit.cloud/v1/folders/$FOLDER_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json"

Organization level

stackit curl -X GET \
"https://telemetry-link.api.stackit.cloud/v1/organizations/$ORGANIZATION_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json"

Project level

stackit curl -X GET \
"https://telemetry-link.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json"

STACKIT Portal

1. On the sidebar, click on Telemetry Link.
2. You see your existing link.

Edit a link

STACKIT API

To edit a telemetry link, you need to call the appropriate endpoint. Each level (folders, organizations and projects) has its own endpoint. The body scheme is equal of each level.

Folder level

stackit curl -X PATCH \
"https://telemetry-link.api.stackit.cloud/v1/folders/$FOLDER_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json" \
--data '<CONFIG_OBJECT>'

Organization level

stackit curl -X PATCH \
"https://telemetry-link.api.stackit.cloud/v1/organizations/$ORGANIZATION_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json" \
--data '<CONFIG_OBJECT>'

Project level

stackit curl -X PATCH \
"https://telemetry-link.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json" \
--data '<CONFIG_OBJECT>'

STACKIT Portal

1. On the sidebar, click on Telemetry Link.
2. You see your existing link. Click on it to edit.

Delete a link

STACKIT API

To delete a telemetry link, you need to call the appropriate endpoint. Each level (folders, organizations and projects) has its own endpoint.

Folder level

stackit curl -X DELETE \
"https://telemetry-link.api.stackit.cloud/v1/folders/$FOLDER_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json"

Organization level

stackit curl -X DELETE \
"https://telemetry-link.api.stackit.cloud/v1/organizations/$ORGANIZATION_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json"

Project level

stackit curl -X DELETE \
"https://telemetry-link.api.stackit.cloud/v1/projects/$PROJECT_ID/regions/$REGION_ID/telemetry-link" \
-H "Content-Type: application/json"

STACKIT Portal

1. On the sidebar, click on Telemetry Link.
2. You see your existing link. Click on the three-dots-menu and select Delete.
3. On the new pane, enter the name of you Telemetry Link and click on Delete.