Docs

Appearance

Integration Examples ​

These examples show common API operations using curl. All examples assume you have an access token (see Authentication).

For the full API reference, see the Scalar API Documentation.

bash
# Set these for the examples below
TOKEN="<your-access-token>"
API="https://api.vion.swiss"
TENANT_ID="<your-tenant-id>"

Finding Your IDs

Call GET /Me to see your tenant and integrator memberships with their IDs:

bash
curl -H "Authorization: Bearer $TOKEN" $API/Me

Get All Services ​

Retrieve the complete service topology for a tenant — all services, properties, and measuring points:

bash
curl -H "Authorization: Bearer $TOKEN" \
  $API/Tenant/$TENANT_ID/Services

The response includes services grouped by edge gateway, with properties and measuring points nested under each service.

Set a Property Value ​

Set a property on a specific service. You need the edge gateway ID, service provider identifier, service identifier, and property identifier:

bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": 22.5 }' \
  "$API/Tenant/$TENANT_ID/Services/{edgeGatewayId}/{serviceProviderIdentifier}/{serviceIdentifier}/property/{propertyIdentifier}"

The value type must match the property type defined in the logic block (number, boolean, string, or enum).

Subscribe to Property Updates ​

Subscribing tells the edge gateway to start publishing property values to the cloud MQTT broker. This is a two-step process:

Step 1: Subscribe via REST API

This triggers the edge gateway to begin sending updates for the specified properties:

bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": [
      {
        "edgeGatewayId": "<gateway-id>",
        "serviceProviderIdentifier": "<sp-id>",
        "serviceIdentifier": "<service-id>",
        "propertyIdentifiers": ["Temperature", "Humidity"]
      }
    ]
  }' \
  "$API/Tenant/$TENANT_ID/Services/subscribeProperties"

Step 2: Connect to the MQTT broker

To receive the updates, connect an MQTT 5.0 client to the cloud broker and subscribe to the property state topics. Each service property includes a topic field in the API response that tells you exactly which MQTT topic to subscribe to.

Here is a minimal example using mqtt.js:

js
import mqtt from "mqtt";

const client = mqtt.connect("wss://ws.vion.swiss:443", {
  protocolVersion: 5,
  username: "",
  password: TOKEN, // JWT access token from authentication
});

// Topic from the Services API response (ServiceProperty.topic)
const topic =
  "v1/{env}/{tenantId}/{edgeGatewayId}/{serviceProviderIdentifier}/{serviceIdentifier}/cloud/sw/properties/state/";

client.on("connect", () => {
  client.subscribe(topic);
});

client.on("message", (topic, message, packet) => {
  const schema = packet.properties?.userProperties?.schema;
  if (schema === "PropertiesStatePayload") {
    const { propertiesState } = JSON.parse(message.toString());
    // propertiesState: [{ propertyIdentifier: "Temperature", value: 22.5 }, ...]
    console.log(propertiesState);
  }
});

Query Measuring Point Data ​

Retrieve time-series data for measuring points within a time range:

bash
curl -H "Authorization: Bearer $TOKEN" \
  "$API/Tenant/$TENANT_ID/MeasuringPoints/data?\
timeRangeStart=2026-03-01T00:00:00Z&\
timeRangeEnd=2026-03-24T00:00:00Z&\
edgeGatewayIds={gatewayId}&\
serviceProviderIdentifiers={spId}&\
serviceIdentifiers={serviceId}&\
measuringPointIdentifiers=Power,Energy"

List Projects ​

bash
curl -H "Authorization: Bearer $TOKEN" \
  $API/Tenant/$TENANT_ID/Projects

List Logic Configurations ​

bash
curl -H "Authorization: Bearer $TOKEN" \
  $API/Tenant/$TENANT_ID/LogicConfigurations

Share a Library with Another Integrator ​

Logic block libraries are Private by default. To grant one of your libraries to another integrator, post to the grants endpoint with the library ID and the grantee integrator's slug. These operations are keyed on your integrator ID:

bash
INTEGRATOR_ID="<your-integrator-id>"

Create a grant from your integrator to the partner integrator (the grantee is named by its globally unique slug, not its name):

bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "logicBlockLibraryId": "<library-id>",
    "granteeIntegratorSlug": "<partner-slug>"
  }' \
  "$API/Integrator/$INTEGRATOR_ID/LogicBlockLibraryGrants"

List the grants you have made on your libraries:

bash
curl -H "Authorization: Bearer $TOKEN" \
  "$API/Integrator/$INTEGRATOR_ID/LogicBlockLibraryGrants"

Revoke a grant by its ID:

bash
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/Integrator/$INTEGRATOR_ID/LogicBlockLibraryGrants/{grantId}"

To make a library Public instead of sharing it with a single integrator, send a PUT with "visibility": "Public" (the name and description fields are required):

bash
curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Library",
    "description": "Smart building blocks",
    "visibility": "Public"
  }' \
  "$API/Integrator/$INTEGRATOR_ID/LogicBlockLibraries/{libraryId}"

Revoking a grant or turning Public off is prospective: running configurations keep working, and the next activation referencing a now-invisible library is blocked.

Full API Reference ​

These examples cover the most common operations. For the complete API with all endpoints, request/response schemas, and interactive testing:

→ Scalar API Reference