Beacontower Core (1.0.11)

Download OpenAPI specification:Download

E-mail: apiteam@beacontower.io Terms of Service

Use this API to interact with core features of Beacon Tower. I.e. Asset Management, Provider Management etc.

Find out more about Swagger

Authentication

Login/Request token

More information

Get a Access Token (JWT)

Authorizations:

bearerAuth

Request Body schema: application/json
required

username	string (User Name)
password	string (Password)

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"password": "string"
}

Response samples

200

Content type

application/json

{"accessToken": "string"
}

Provider

Manage Providers

More information

Get Providers

Get all Providers or filter by type

Authorizations:

bearerAuth

query Parameters

type	string Filter by type. Examples are "iothub" and "import"

Responses

Response samples

200

Content type

application/json

[{"id": "myProviderId",
"type": "iothub",
"displayName": "My Provider",
"description": "Description of My Provider"
}
]

Create Provider

Create a new provider

Authorizations:

bearerAuth

Request Body schema: application/json
required

Provider

id	string
type required	string
displayName required	string
description	string
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

{"id": "myProviderId",
"type": "iothub",
"displayName": "My Provider",
"description": "Description of My Provider",
"organizationId": "org1"
}

Create or update an existing Provider

Create or update Provider by Id

Authorizations:

bearerAuth

path Parameters

providerId

required

string

Provider id

Request Body schema: application/json
required

Create or update a Provider

type	string
displayName required	string
description	string

Responses

Request samples

Payload

Content type

application/json

{"type": "iothub",
"displayName": "My Provider",
"description": "Description of My Provider"
}

Get provider by ID

Returns a single Provider

Authorizations:

bearerAuth

path Parameters

providerId

required

string

ID of Provider to return

Responses

Response samples

200

Content type

application/json

{"id": "myProviderId",
"type": "iothub",
"displayName": "My Provider",
"description": "Description of My Provider"
}

Deletes a provider

Delete a provider

Authorizations:

bearerAuth

path Parameters

providerId

required

string

Provider id to delete

Responses

ProviderClient

Manage Provider Clients

More information

Get Clients

Get all clients from a Provider

Authorizations:

bearerAuth

path Parameters

providerId

required

string

Requests a list of clients from a Provider

Responses

Response samples

200

Content type

application/json

[{"id": "myClientId",
"displayName": "My Client",
"description": "My Provider Client description",
"templateid": "fc006ddc-e939-4d66-bf6d-4b53b10d812b",
"enabled": true
}
]

Create Client

Create a new client

Authorizations:

bearerAuth

path Parameters

providerId

required

string

Creates a new Provider Client

Request Body schema: application/json
required

Provider Client

id required	string
displayName required	string
description	string
enabled	boolean
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

{"id": "myClientId",
"displayName": "My Client",
"description": "My Provider Client description",
"enabled": true,
"organizationId": "string"
}

Get Client

Get a client from Provider including Provider Data

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

query Parameters

componentId

string

Component identifier (module)

Responses

Response samples

200

Content type

application/json

{"id": "myClientId",
"displayName": "My Client",
"description": "My Provider Client description",
"templateId": "fc006ddc-e939-4d66-bf6d-4b53b10d812b",
"templateApplied": "2020-02-08 09:30:26.123Z",
"enabled": true,
"providerData": {"someProviderDataPropertyName": "someProviderDataPropertyValue"
}
}

Delete Client

Delete a client

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

Responses

Update Client properties

Update properties on a Provider Client

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

Request Body schema: application/json
required

Update a subset of properties on a Provider Client

displayName	string or null
description	string or null
enabled	boolean or null Default: true

Responses

Request samples

Payload

Content type

application/json

{"displayName": "My Provider Client Display name",
"description": "My Provider Client Description",
"enabled": true
}

Provisions a provider client onto it's provider infrastructure

If a template is used, include a refrence to the template using templateId

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

Request Body schema: application/json
required

Provision request body. Defaults: Iot-device, Sas authentication, enabled

templateId	string Template Id
options required	object Controls behaviour for the provision operation. See examples.

Responses

Request samples

Payload

Content type

application/json

Example

Provision an iot-device onto iot-hub provider (Minimal))

{"Options": {"hub": "someHubName"
}
}

Unprovisions a provider client from it's provider infrastructure

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

Responses

Run direct method command

Synchronously execute a remote mehod on the Client

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

Request Body schema: application/json
required

Direct mehod request with optional payload

componentId	string or null
method	string
payload	object or null

Responses

Request samples

Payload

Content type

application/json

{"componentId": "sensehat",
"method": "lightsOn",
"payload": {"theme": "christmas01"
}
}

Get reported properties

Get reported properties for a Provider Client

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

query Parameters

componentId

string

Component identifier (module)

Responses

Response samples

200

Content type

application/json

{"tempsettings": {"hightemp": 20,
"lowtem": 10
},
"updatefreq": 20
}

Get desired properties

Get desired properties for a Provider Client

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

query Parameters

componentId

string

Component identifier (module)

Responses

Response samples

200

Content type

application/json

{"tempsettings": {"hightemp": 20,
"lowtemp": 10
},
"updatefreq": 20
}

Set desired properties

Set desired properties on a Provider Client

Authorizations:

bearerAuth

path Parameters

providerId required	string ProviderId
clientId required	string ClientId

Request Body schema: application/json
required

Desired properties body

componentId	string or null
	object

Responses

Request samples

Payload

Content type

application/json

{"componentId": "sensehat",
"tempsettings": {"hightemp": 20,
"lowtemp": 10,
"updatefreq": 20
}
}

ProviderTemplate

Manage Provider Templates

More information

Get Templates

Get all templates for a Provider

Authorizations:

bearerAuth

query Parameters

tagFilter

string

Example: tagFilter=AssetModel=myModel

Only fetch templates with the matching tags.

Responses

Response samples

200

Content type

application/json

[{"id": "e6c27027-6c25-4e81-b6a0-a9bd9af184eb",
"displayName": "Default iot-hub edge device template",
"description": "This template is used to provision edge-devices onto iot-hub",
"enabled": true,
"options": {"hub": "iothub-name",
"isEdge": true,
"edgeDeviceTemplateOptions": {"manifest": { },
"deviceDesiredProperties": {"test": 1
},
"modulesDesiredProperties": {"sensehat": {"test": 1
}
}
}
}
}
]

Create a Template

Create a new Provider Template

Authorizations:

bearerAuth

Request Body schema: application/json
required

Create Template body

	object
displayName required	string
description	string
enabled	string Default: true If disabled, no new clients can be created using this template
options	object Provider specific options
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

Example

IotHub - Iot device

{"tags": {"AssetModel": ["model1",
"model2"
],
"PublishingStatus": ["Draft"
]
},
"displayName": "Default iot-hub device template",
"description": "This template is used to provision iot-devices onto iot-hub",
"enabled": false,
"options": {"hub": "iothub-name",
"isEdge": false,
"iotDeviceTemplateOptions": {"desiredProperties": {"test": 1
}
}
},
"organizationId": "org1"
}

Response samples

200

Content type

application/json

{"id": "e6c27027-6c25-4e81-b6a0-a9bd9af184eb",
"displayName": "Default iot-hub edge device template",
"description": "This template is used to provision edge-devices onto iot-hub",
"enabled": true,
"options": {"hub": "iothub-name",
"isEdge": true,
"edgeDeviceTemplateOptions": {"manifest": { },
"deviceDesiredProperties": {"test": 1
},
"modulesDesiredProperties": {"sensehat": {"test": 1
}
}
}
}
}

Get Template

Get a provider template

Authorizations:

bearerAuth

path Parameters

templateId

required

string

TemplateId

Responses

Response samples

200

Content type

application/json

{"id": "e6c27027-6c25-4e81-b6a0-a9bd9af184eb",
"displayName": "Default iot-hub edge device template",
"description": "This template is used to provision edge-devices onto iot-hub",
"enabled": true,
"options": {"hub": "iothub-name",
"isEdge": true,
"edgeDeviceTemplateOptions": {"manifest": { },
"deviceDesiredProperties": {"test": 1
},
"modulesDesiredProperties": {"sensehat": {"test": 1
}
}
}
}
}

Update Provider Template

Update an exising Provider Template

Authorizations:

bearerAuth

path Parameters

templateId

required

string

TemplateId

Request Body schema: application/json
required

Update Template body

	object
displayName	string
description	string
enabled	string If disabled, no new clients can be created using this template
options	object Provider specific options

Responses

Request samples

Payload

Content type

application/json

{"tags": {"property1": ["string"
],
"property2": ["string"
]
},
"displayName": "Default iot-hub edge device template",
"description": "This template is used to provision generic edge-devices onto iot-hub",
"enabled": true,
"options": {"hub": "iothub-name",
"isEdge": true,
"edgeDeviceTemplateOptions": {"manifest": { },
"deviceDesiredProperties": {"test": 1
},
"modulesDesiredProperties": {"sensehat": {"test": 1
}
}
}
}
}

Delete Template

Delete a Provider Template

Authorizations:

bearerAuth

path Parameters

templateId

required

string

TemplateId

Responses

Alarms

Manage Alarms

More information

Fetch alarms or alarm if alarmId is provided

Authorizations:

bearerAuth

query Parameters

alarmId

string

Alarm id

Responses

Create a new alarm

Authorizations:

bearerAuth

Request Body schema: application/json
required

Alarm object

name required	string Name of the alarm
description	string Description of the alarm
severity	integer Severity of the alarm
id	string Id of the alarm
entityTypeId	string Id of the entity type
entityIds	Array of strings
type	string Type of the alarm
condition	string JSONLogic condition of the alarm

Responses

Request samples

Payload

Content type

application/json

{"name": "alarm1",
"description": "My alarm",
"severity": 0,
"id": "alarm1",
"entityTypeId": "dtmi:com:example:TemperatureController;1",
"entityIds": ["device1"
],
"type": "dtmi:com:example:TemperatureController;1",
"condition": "string"
}

Delete an alarm

Authorizations:

bearerAuth

query Parameters

alarmId

required

string

Alarm id

Responses

Update an alarm

Authorizations:

bearerAuth

query Parameters

alarmId

required

string

Alarm id

Request Body schema: application/json
required

Alarm object

name required	string Name of the alarm
description	string Description of the alarm
severity	integer Severity of the alarm
id	string Id of the alarm
entityTypeId	string Id of the entity type
entityIds	Array of strings
type	string Type of the alarm
condition	string JSONLogic condition of the alarm

Responses

Request samples

Payload

Content type

application/json

{"name": "alarm1",
"description": "My alarm",
"severity": 0,
"id": "alarm1",
"entityTypeId": "dtmi:com:example:TemperatureController;1",
"entityIds": ["device1"
],
"type": "dtmi:com:example:TemperatureController;1",
"condition": "string"
}

returns all alarms that are active for the alarms

returns all alarms that are active for the alarms accessible for the user

Authorizations:

bearerAuth

Responses

get alarm status for a specific entity

Authorizations:

bearerAuth

path Parameters

entityId

required

string

Entity id

Responses

alarm status id to acknowledge

Authorizations:

bearerAuth

path Parameters

alarmStatusId

required

string

Alarm status id

Responses

Asset

Manage Assets

More information

Get assets

Get Assets that the current user has the view resource permission on.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "temperatureDevice1",
"modelId": "dtmi:series200:tempSensor;1",
"displayName": "Temperature Sensor 1",
"description": "Measures temperature in °C at 2 Hz.",
"contentBindings": [{"endpointId": "temp",
"instanceId": "device1"
},
{"endpoint": "pressure",
"instanceId": "device1"
}
],
"authorizationContext": {"viewableByOrganizations": ["org1",
"org2"
]
}
}
]

Create asset

Create Asset requires the asset_management privilege. the current user must also have the view resource permission on the model.

Authorizations:

bearerAuth

Request Body schema: application/json
required

id required	string Instance BTI
modelId required	string Model BTI
displayName required	string
description	string
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

{"id": "temperatureDevice1",
"modelId": "dtmi:series200:tempSensor;1",
"displayName": "Temperature Sensor 1",
"description": "Measures temperature in °C at 2 Hz.",
"organizationId": "myOrg"
}

Response samples

201

Content type

application/json

{"id": "temperatureDevice1",
"modelId": "dtmi:series200:tempSensor;1",
"displayName": "Temperature Sensor 1",
"description": "Measures temperature in °C at 2 Hz."
}

Get asset

Get Asset details. The current user must have the view resource permission on the Asset.

Authorizations:

bearerAuth

path Parameters

assetId

required

string

Instance BTI

Responses

Response samples

200

Content type

application/json

{"id": "temperatureDevice1",
"modelId": "dtmi:series200:tempSensor;1",
"displayName": "Temperature Sensor 1",
"description": "Measures temperature in °C at 2 Hz.",
"contentBindings": [{"endpointId": "temp",
"instanceId": "device1"
},
{"endpoint": "pressure",
"instanceId": "device1"
}
],
"authorizationContext": {"viewableByOrganizations": ["org1",
"org2"
]
}
}

Update asset

Patch the Asset with new displayName or description. The current user must have the manage resource permission on the Asset.

Authorizations:

bearerAuth

path Parameters

assetId

required

string

Instance BTI

Request Body schema: application/json
required

displayName	string
description	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Smart fridge",
"description": "Detects and notifies when you are running out of food."
}

Delete asset

Authorizations:

bearerAuth

path Parameters

assetId

required

string

Instance BTI

Responses

Get assets of model

Authorizations:

bearerAuth

path Parameters

modelId

required

string

Instance BTI

Responses

Response samples

200

Content type

application/json

{"id": "temperatureDevice1",
"modelId": "dtmi:series200:tempSensor;1",
"displayName": "Temperature Sensor 1",
"description": "Measures temperature in °C at 2 Hz.",
"contentBindings": [{"endpointId": "temp",
"instanceId": "device1"
},
{"endpoint": "pressure",
"instanceId": "device1"
}
],
"authorizationContext": {"viewableByOrganizations": ["org1",
"org2"
]
}
}

Bind asset

The most common case is to just use autobind with a default binding description.

The bind endpoint constructs a set of content bindings by doing the following steps:

Add contentBindings, if any.
Run autobind to create content bindings for the remaining unbound contents.

So it is possible to specify some content bindings directly and run autobind on the remaining contents.

Autobind

This functionality takes an endpoint instance ID and a binding description ID and creates a set of content bindings. These content bindings do not overwrite other content bindings binding to the same content.

If autobindBindingDescriptionId is omitted it will assume a default binding description will be used. This binding description ID is constructed from the model or the provider type of the endpoint instance that autobindEndpointInstanceId refers to. The default binding description will be generated if it does not exist.

NOTE: Using autobind with an implicit binding description ID is currently only supported when binding to a provider client.

Authorizations:

bearerAuth

path Parameters

assetId

required

string

Instance BTI

Request Body schema: application/json
required

	Array of objects (EndpointBinding) Manually defined endpoint bindings.
ignoreEndpointsIds	Array of strings Local endpoint IDs to not bind with autobind nor binding descriptions.
	Array of objects (BindingDescriptionBindDefinition) Binding descriptions and their remote instance definitions, bound in order specified in this array.
autobindRemoteInstanceIds	Array of strings Instance IDs used for the autobind function, bound in order specified in this array.

Responses

Request samples

Payload

Content type

application/json

Example

Autobind with default binding description

The common and simplest case of binding an asset to a provider client through autobind with a default binding description.

{"autobindRemoteInstanceIds": ["defaultIotHubProvider::device1"
]
}

Response samples

200

Content type

application/json

{"endpointBindings": [{"localEndpointId": "string",
"remoteEndpointIds": [{"name": "string",
"endpointId": "string"
}
],
"bindingType": "default",
"transform": { },
"inverseTransform": { }
}
],
"ignoreEndpointIds": ["string"
],
"bindingDescriptions": [{"bindingDescriptionId": "string",
"instances": [{"instanceName": "string",
"instanceId": "string"
}
],
"localComponentEndpointId": "string"
}
],
"autobindRemoteInstanceIds": ["string"
]
}

Execute command

Send a command to an Asset to be executed. If the command endpoint of the Asset is bound, the command will be forwarded to the bound endpoint. The request returns the current status of the executed command.

This operation requires the manage resource permission on the Asset.

Authorizations:

bearerAuth

path Parameters

assetId required	string AssetId
commandName required	string CommandName

Request Body schema: application/json
optional

Asset command payload

any

Responses

Request samples

Payload

Content type

application/json

null

Response samples

200

Content type

application/json

{"commandId": "myDevice1.start",
"requestTimestamp": "2024-04-04T04:04:04.000Z",
"responseTimestamp": "2024-04-04T04:04:06.000Z",
"status": "running",
"statusMessage": "Command is running",
"requestPayload": null,
"responsePayload": null,
"correlationId": "CB2886DC-6CFE-4AB3-B3BC-76B51DFE4B1B"
}

Get command status

Get the status of the last executed command.

Authorizations:

bearerAuth

path Parameters

assetId required	string AssetId
commandName required	string CommandName

Responses

Response samples

200

Content type

application/json

{"commandId": "myDevice1.start",
"requestTimestamp": "2024-04-04T04:04:04.000Z",
"responseTimestamp": "2024-04-04T04:04:06.000Z",
"status": "running",
"statusMessage": "Command is running",
"requestPayload": null,
"responsePayload": null,
"correlationId": "CB2886DC-6CFE-4AB3-B3BC-76B51DFE4B1B"
}

Update desired properties

Update desired properties of an Asset

Authorizations:

bearerAuth

path Parameters

assetId

required

string

AssetId

Request Body schema: application/json
required

Asset desired properties body

object (assetProperties)

Responses

Request samples

Payload

Content type

application/json

{"assetComponent": {"reportInterval": 10,
"connectionConfigObject": {"connectionString": "HostName=iothub-somethingsomething-1234567-1234567-1234567-1234567.azure-devices.net;DeviceId=MyDevice;SharedAccessKey=1234567890123456789012345678901234567890123456789012345678901234="
}
},
"maxFlowThreshold": 230,
"location": "somewhere",
"meterType": "Meter3000"
}

Get desired properties

Get desired properties of an Asset

Authorizations:

bearerAuth

path Parameters

assetId

required

string

AssetId

Responses

Response samples

200

Content type

application/json

{"assetComponent": {"reportInterval": 10,
"connectionConfigObject": {"connectionString": "HostName=iothub-somethingsomething-1234567-1234567-1234567-1234567.azure-devices.net;DeviceId=MyDevice;SharedAccessKey=1234567890123456789012345678901234567890123456789012345678901234="
}
},
"maxFlowThreshold": 230,
"location": "somewhere",
"meterType": "Meter3000"
}

Get reported properties

Get reported properties of an Asset

Authorizations:

bearerAuth

path Parameters

assetId

required

string

AssetId

Responses

Response samples

200

Content type

application/json

{"assetComponent": {"reportInterval": 10,
"connectionConfigObject": {"connectionString": "HostName=iothub-somethingsomething-1234567-1234567-1234567-1234567.azure-devices.net;DeviceId=MyDevice;SharedAccessKey=1234567890123456789012345678901234567890123456789012345678901234="
}
},
"maxFlowThreshold": 230,
"location": "somewhere",
"meterType": "Meter3000"
}

Migrate an asset to a new model

Authorizations:

bearerAuth

Request Body schema: application/json
required

Migration object

targetAssetModelId required	string (Target Asset Model Id)
assetIds required	Array of strings (Array of Asset Ids)

Responses

Request samples

Payload

Content type

application/json

{"targetAssetModelId": "string",
"assetIds": ["string"
]
}

Dashboard

Manage Dashboards

More information

Get dashboards

Get dashboards that the current user has the view resource permission on.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "dashboard1",
"data": {"someDashboardSpecificData": "data"
},
"displayName": "Temperature Dashboard1",
"description": "Shows temperatures over time for Assets of model x",
"authorizationContext": {"viewableByOrganizations": ["org1",
"org2"
]
}
}
]

Create dashboard

Create dashboard requires the dashboard_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

data	object
displayName required	string
description	string
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Temperature Dashboard1",
"description": "Shows temperatures over time for Assets of model x",
"organizationId": "myOrg",
"data": {"someDashboardSpecificData": "data"
}
}

Response samples

201

Content type

application/json

{"id": "dashboard1",
"data": {"someDashboardSpecificData": "data"
},
"displayName": "Temperature Dashboard1",
"description": "Shows temperatures over time for Assets of model x",
"authorizationContext": {"viewableByOrganizations": ["org1",
"org2"
]
}
}

Get dashboard

Get dashboard details. The current user must have the view resource permission on the dashboard.

Authorizations:

bearerAuth

path Parameters

dashboardId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "dashboard1",
"data": {"someDashboardSpecificData": "data"
},
"displayName": "Temperature Dashboard1",
"description": "Shows temperatures over time for Assets of model x",
"authorizationContext": {"viewableByOrganizations": ["org1",
"org2"
]
}
}

Update dashboard

Patch the Dashboard with new displayName, description or data. The current user must have the manage resource permission on the Dashboard.

Authorizations:

bearerAuth

path Parameters

dashboardId

required

string

Request Body schema: application/json
required

displayName	string
description	string
data	object

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Temperature Dashboard1",
"description": "Shows temperatures over time for Assets of model x"
}

Delete dashboard

Authorizations:

bearerAuth

path Parameters

dashboardId

required

string

Responses

Model

Manage Models

More information

Get all models

Authorizations:

bearerAuth

Responses

Create a new model

Authorizations:

bearerAuth

Request Body schema: application/json

object

Responses

Request samples

Payload

Content type

application/json

{ }

Get model

Authorizations:

bearerAuth

path Parameters

modelId

required

string

ID of model

Responses

Delete model

Authorizations:

bearerAuth

path Parameters

modelId

required

string

ID of model

Responses

Get DTDL model

Authorizations:

bearerAuth

path Parameters

modelId

required

string

ID of model

Responses

Validate a DTDL model

Authorizations:

bearerAuth

Request Body schema: application/json
required

object

Responses

Request samples

Payload

Content type

application/json

{ }

Model draft

Manage Model drafts

More information

Get model drafts

Authorizations:

bearerAuth

Responses

Create model draft

Authorizations:

bearerAuth

Request Body schema: application/json
required

object

Responses

Request samples

Payload

Content type

application/json

{ }

Get model draft

Authorizations:

bearerAuth

path Parameters

modelDraftId

required

string

Responses

Update model draft

Authorizations:

bearerAuth

path Parameters

modelDraftId

required

string

Request Body schema: application/json
required

object

Responses

Request samples

Payload

Content type

application/json

{ }

Delete model draft

Authorizations:

bearerAuth

path Parameters

modelDraftId

required

string

Responses

Promote model draft

Authorizations:

bearerAuth

path Parameters

modelDraftId

required

string

Responses

Binding description

Manage binding descriptions

More information

Get binding descriptions

Authorizations:

bearerAuth

Responses

Create binding description

Authorizations:

bearerAuth

Request Body schema: application/json
required

object

Responses

Request samples

Payload

Content type

application/json

{ }

Get binding description

Authorizations:

bearerAuth

path Parameters

bindingDescriptionId

required

string

Responses

Delete binding description

Authorizations:

bearerAuth

path Parameters

bindingDescriptionId

required

string

Responses

Update binding description

Authorizations:

bearerAuth

path Parameters

bindingDescriptionId

required

string

Request Body schema: application/json
required

object

Responses

Request samples

Payload

Content type

application/json

{ }

Get binding descriptions for asset model

Authorizations:

bearerAuth

path Parameters

modelId

required

string

Responses

Generate a binding description from a model ID and an endpoint ID

Authorizations:

bearerAuth

path Parameters

modelId required	string
endpointId required	string

Responses

Binding description draft

Manage binding description drafts

More information

Get binding description drafts

Authorizations:

bearerAuth

Responses

Create binding description draft

Authorizations:

bearerAuth

Request Body schema: application/json
required

object

Responses

Request samples

Payload

Content type

application/json

{ }

Get binding description draft

Authorizations:

bearerAuth

path Parameters

bindingDescriptionDraftId

required

string

Responses

Delete binding description draft

Authorizations:

bearerAuth

path Parameters

bindingDescriptionDraftId

required

string

Responses

Update binding description draft

Authorizations:

bearerAuth

path Parameters

bindingDescriptionDraftId

required

string

Request Body schema: application/json
required

object

Responses

Request samples

Payload

Content type

application/json

{ }

Get binding description drafts for model

Authorizations:

bearerAuth

path Parameters

modelId

required

string

Responses

Promote binding description draft

Authorizations:

bearerAuth

path Parameters

bindingDescriptionId

required

string

Responses

Tenant

Manage tenants (PREVIEW)

More information

Get tenants

Fetches all tenants

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"displayName": "string",
"description": "string",
"permissions": ["string"
]
}
]

Get a specific tenant

Authorizations:

bearerAuth

path Parameters

tenantId

required

string

Tenant identifier

Responses

Response samples

200

Content type

application/json

{"id": "string",
"displayName": "string",
"description": "string",
"permissions": ["string"
]
}

Organization

Manage organizations

More information

Get organizations

Fetches all organizations that the user has read access to

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "org1",
"parentOrganizationId": null,
"displayName": "My Org. name",
"description": "My root Org. (Privilege restrictions from Tenant)",
"contacts": {"notifications": {"userGroups": ["string"
],
"users": ["string"
]
}
},
"privileges": ["asset_management"
]
}
]

Create organization

Authorizations:

bearerAuth

Request Body schema: application/json
required

parentOrganizationId	string A sub-organization's privileges are limited to a subset of the parent organization's privileges or if this is a root organization, to the tenant's privileges. Set to null if this is a root organization.
displayName required	string
description	string
privileges	Array of strings (Privilege) Items Enum: "asset_management" "dashboard_management" "user_management" "tree_management" "model_management" "alarm_management" "organization_management" "provider_management" "provider_client_management" "notification_management" "contact_group_management" "resource_item_management" List of privileges that the organization should have. These must be a subset of any parent organization's or the tenant's privileges.
	object (OrgContacts)
	object (OrgRelations) Describes the relationships that should be set up for this organization. Relationships are used to manage permissions. I.e the permissions to features the organization it self has, who can access the organization and in what capacity, as well as what resources the organization controls and in what capacity.

Responses

Request samples

Payload

Content type

application/json

{"parentOrganizationId": null,
"displayName": "myOrg",
"description": "My root Org. (Privilege restrictions from Tenant)",
"privileges": ["asset_management"
],
"contacts": {"notifications": {"userGroups": ["string"
],
"users": ["string"
]
}
},
"relations": {"GroupToOrgRelations": [{"groupId": "group1",
"relation": "owner"
}
],
"UserToOrgRelations": [{"userId": "user1",
"relation": "owner"
}
],
"OrgToResourceRelations": [{"resourceId": "model1",
"resourceType": "organization",
"relation": "owner"
}
]
}
}

Response samples

201

Content type

application/json

{"id": "org1",
"parentOrganizationId": null,
"displayName": "My Org. name",
"description": "My root Org. (Privilege restrictions from Tenant)",
"contacts": {"notifications": {"userGroups": ["string"
],
"users": ["string"
]
}
},
"privileges": ["asset_management"
]
}

Get a specific organization

Authorizations:

bearerAuth

path Parameters

organizationId

required

string

Organization identifier

Responses

Response samples

200

Content type

application/json

{"id": "org1",
"parentOrganizationId": null,
"displayName": "My Org. name",
"description": "My root Org. (Privilege restrictions from Tenant)",
"contacts": {"notifications": {"userGroups": ["string"
],
"users": ["string"
]
}
},
"privileges": ["asset_management"
]
}

Change an organizations properties

Authorizations:

bearerAuth

path Parameters

organizationId

required

string

Organization identifier

Request Body schema: application/json
required

non-empty

displayName	string
description	string
	object (OrgContacts)
privileges	Array of strings (Privilege) Items Enum: "asset_management" "dashboard_management" "user_management" "tree_management" "model_management" "alarm_management" "organization_management" "provider_management" "provider_client_management" "notification_management" "contact_group_management" "resource_item_management"

Responses

Request samples

Payload

Content type

application/json

{"displayName": "My new display name",
"description": "My new description",
"contacts": {"notifications": {"userGroups": ["string"
],
"users": ["string"
]
}
},
"privileges": ["asset_management"
]
}

Delete Organization

Authorizations:

bearerAuth

path Parameters

organizationId

required

string

Organization Identifier

Responses

Get an organization's settings

Authorizations:

bearerAuth

path Parameters

organizationId

required

string

Responses

Set an organization's settings

Authorizations:

bearerAuth

path Parameters

organizationId

required

string

Request Body schema: application/json
required

The organization's new settings

object

Responses

Request samples

Payload

Content type

application/json

{ }

User

Manage users

More information

Get users

Fetches all users

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"displayName": "string",
"email": "string",
"phoneNumber": "string"
}
]

Create user

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName required	string
email required	string
password required	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "string",
"email": "string",
"password": "string"
}

Response samples

201

Content type

application/json

{"id": "string",
"displayName": "string",
"email": "string",
"phoneNumber": "string"
}

Get a specific user

Authorizations:

bearerAuth

path Parameters

userId

required

string

User identifier

Responses

Response samples

200

Content type

application/json

{"id": "string",
"displayName": "string",
"email": "string",
"phoneNumber": "string"
}

Change a users properties

Authorizations:

bearerAuth

path Parameters

userId

required

string

User identifier

Request Body schema: application/json
required

displayName	string
phoneNumber	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "string",
"phoneNumber": "string"
}

Delete User

Authorizations:

bearerAuth

path Parameters

userId

required

string

User Identifier

Responses

Get a specific user's settings

Authorizations:

bearerAuth

path Parameters

userId

required

string

User identifier

Responses

Response samples

200

Content type

application/json

{ }

Set a specific user's settings

Authorizations:

bearerAuth

path Parameters

userId

required

string

User identifier

Request Body schema: application/json
required

The user's new settings

object

Responses

Request samples

Payload

Content type

application/json

{ }

Group

Manage user groups

More information

Get groups

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "string",
"displayName": "string",
"description": "string"
}
]

Create group

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName required	string
description	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "string",
"description": "string"
}

Response samples

201

Content type

application/json

{"id": "string",
"displayName": "string",
"description": "string"
}

Get a specific group

Authorizations:

bearerAuth

path Parameters

groupId

required

string

Group identifier

Responses

Response samples

200

Content type

application/json

{"id": "string",
"displayName": "string",
"description": "string"
}

Change a groups properties

Authorizations:

bearerAuth

path Parameters

groupId

required

string

Group identifier

Request Body schema: application/json
required

displayName	string
description	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "string",
"description": "string"
}

Delete group

Authorizations:

bearerAuth

path Parameters

groupId

required

string

Group Identifier

Responses

Auth-Relation

Manage relations for authorization

More information

Create a relation between a subject and a resource

Authorizations:

bearerAuth

Request Body schema: application/json

Array

subjectType required	string Enum: "user" "group" "organization" "tenant" "node"
subjectId required	string
resourceType required	string Enum: "environment" "tenant" "organization" "group" "user" "node" "asset" "model" "binding_description" "alarm" "provider" "provider_client" "provider_template" "dashboard" "notification" "contact_group" "resource_item"
resourceId required	string
relation required	string Enum: "owner" "member" "manager" "viewer" "user_manager" "asset_manager" "model_manager" "notification_manager" "contact_group_manager" "alarm_manager" "provider_manager" "provider_client_manager" "tree_manager" "organization_manager" "dashboard_manager" "resource_item_manager" "parent"

Responses

Request samples

Payload

Content type

application/json

[{"subjectType": "user",
"subjectId": "user1",
"resourceType": "asset",
"resourceId": "asset1",
"relation": "manager"
}
]

Find relations

Authorizations:

bearerAuth

Request Body schema: application/json

resourceType required	string Enum: "organization" "group" "user" "node" "asset" "model" "binding_description" "alarm" "provider" "provider_client" "provider_template" "dashboard" "notification" "contact_group" "resource_item"
optionalResourceId	string
optionalRelation	string Enum: "owner" "member" "manager" "viewer" "user_manager" "asset_manager" "model_manager" "notification_manager" "contact_group_manager" "alarm_manager" "provider_manager" "provider_client_manager" "tree_manager" "organization_manager" "dashboard_manager" "resource_item_manager" "parent"
	object

Responses

Request samples

Payload

Content type

application/json

{"resourceType": "organization",
"optionalResourceId": "assetModel1",
"optionalRelation": "owner",
"optionalSubjectFilter": {"subjectType": "organization",
"optionalSubjectId": "org1"
}
}

Response samples

200

Content type

application/json

[{"subjectType": "organization",
"subjectId": "org1",
"resourceType": "environment",
"resourceId": "assetModel1",
"relation": "owner"
}
]

Remove a relation between a subject and a resource

Authorizations:

bearerAuth

path Parameters

subjectType required	string Subject type
subjectId required	string Subject Id
resourceType required	string Resource type
resourceId required	string Resource Id
relation required	string relation

Responses

Permission

Work with permissions

More information

Make a permissions check

Authorizations:

bearerAuth

Request Body schema: application/json

Array

subjectType required	string Enum: "user" "group" "organization" "tenant" "node"
subjectId	string
resourceType required	string Enum: "organization" "group" "user" "node" "asset" "model" "binding_description" "alarm" "provider" "provider_client" "provider_template" "dashboard" "notification" "contact_group" "resource_item"
resourceId required	string
permission required	string Enum: "view" "manage" "delete" "share"

Responses

Request samples

Payload

Content type

application/json

[{"subjectType": "user",
"subjectId": "user1",
"resourceType": "asset",
"resourceId": "asset1",
"permission": "manage"
}
]

Response samples

200

Content type

application/json

[{"subjectType": "user",
"subject": "user1",
"resourceType": "asset",
"resourceId": "user1",
"permission": "manage",
"result": false
}
]

Looks up resources of a specified type that a subject has a specified permission on

Authorizations:

bearerAuth

Request Body schema: application/json

subjectType required	string Enum: "user" "group" "organization" "tenant" "node"
subjectId required	string
resourceType required	string Enum: "organization" "group" "user" "node" "asset" "model" "binding_description" "alarm" "provider" "provider_client" "provider_template" "dashboard" "notification" "contact_group" "resource_item"
permission required	string Enum: "view" "manage" "delete" "share"

Responses

Request samples

Payload

Content type

application/json

{"subjectType": "user",
"subjectId": "string",
"resourceType": "asset",
"permission": "manage"
}

Response samples

200

Content type

application/json

["asset1",
"asset2",
"asset3"
]

Looks up wich subjects have permissions on a resource.

Authorizations:

bearerAuth

Request Body schema: application/json

resourceType required	string Enum: "organization" "group" "user" "node" "asset" "model" "binding_description" "alarm" "provider" "provider_client" "provider_template" "dashboard" "notification" "contact_group" "resource_item"
resourceId required	string
subjectType required	string Enum: "user" "group" "organization" "tenant" "node"
permission required	string Enum: "view" "manage" "delete" "share"

Responses

Request samples

Payload

Content type

application/json

{"resourceType": "asset",
"resourceId": "asset1",
"subjectType": "user",
"permission": "manage"
}

Response samples

200

Content type

application/json

["user1",
"user2",
"user3"
]

Privilege

Work with privileges

More information

Make a Privilege check

Authorizations:

bearerAuth

Request Body schema: application/json

Array

subjectType required	string Enum: "user" "group" "organization" "tenant"
subjectId required	string
privilege required	string (Privilege) Enum: "asset_management" "dashboard_management" "user_management" "tree_management" "model_management" "alarm_management" "organization_management" "provider_management" "provider_client_management" "notification_management" "contact_group_management" "resource_item_management"
organizationId	string Used when subjectType is group or user

Responses

Request samples

Payload

Content type

application/json

[{"subjectType": "user",
"subjectId": "user1",
"privilege": "asset_management",
"organizationId": "org1"
}
]

Response samples

200

Content type

application/json

[{"subjectType": "user",
"subjectId": "user1",
"organizationId": "org1",
"privilege": "asset_management",
"result": false
}
]

Graph

Graph management

More information

Create a new node

Create a new node that can be part of a tree or the start node of a tree

Authorizations:

bearerAuth

Request Body schema: application/json
required

Create node body

displayName required	string
description	string
parentNodeId	string
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "string",
"description": "string",
"parentNodeId": "string",
"organizationId": "string"
}

Response samples

201

Content type

application/json

{"id": "2342345",
"displayName": "Node1",
"description": "My Node 1"
}

Get a node

Authorizations:

bearerAuth

path Parameters

id

required

string

Responses

Response samples

200

Content type

application/json

[{"id": "2342345",
"displayName": "Node1",
"description": "My Node 1"
}
]

Update a node

Patch the Node with new displayName or description

Authorizations:

bearerAuth

path Parameters

id

required

string

Request Body schema: application/json
required

displayName	string
description	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "NewDisplayName1"
}

Delete a node. Any child nodes will be deleted. Any linked resources will be unlinked.

Authorizations:

bearerAuth

path Parameters

id

required

string

Responses

Link graph items by creating an edge in the graph

Authorizations:

bearerAuth

Request Body schema: application/json

fromType required	string Enum: "node" "asset"
fromId required	string
toType required	string Enum: "node" "asset" "dashboard"
toId required	string
relation required	string Value: "CONTAINS"

Responses

Request samples

Payload

Content type

application/json

{"fromType": "node",
"fromId": 2342352,
"toType": "asset",
"toId": 3453453,
"relation": "CONTAINS"
}

Find relations

Authorizations:

bearerAuth

Request Body schema: application/json

fromId required	string
fromType required	string Enum: "node" "asset" "dashboard"

Responses

Request samples

Payload

Content type

application/json

{"fromId": 474334,
"fromType": "node"
}

Response samples

200

Content type

application/json

[{"id": 3245342,
"fromType": "node",
"fromId": 4743564,
"toType": "node",
"toId": 3453435,
"relation": "CONTAINS"
}
]

Remove a relation between a subject and a resource

Authorizations:

bearerAuth

path Parameters

edgeId

required

string

Edge Id

Responses

Get list of trees (Nodes that are unparented)

Get a list of start nodes (trees) available for the user.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "2342345",
"displayName": "Node1",
"description": "My Node 1"
}
]

Get a tree based on a start node

Get a specific tree

Authorizations:

bearerAuth

path Parameters

startNodeId

required

string

Optional start node Id

query Parameters

depth

integer

Optional search depth in the graph

Responses

Response samples

200

Content type

application/json

{"id": "345335",
"displayName": "Node1",
"description": "My Node 1",
"type": "NODE",
"edge": {"id": "2342341",
"fromType": "NODE",
"fromId": "2343254",
"toType": "NODE",
"toId": "653522",
"relation": "CONTAINS"
},
"children": [{"id": "345335",
"displayName": "Asset1",
"description": "Asset1 Description",
"type": "ASSET",
"edge": {"id": "4332543",
"fromType": "NODE",
"fromId": "2342341",
"toType": "ASSET",
"toId": "345335",
"relation": "CONTAINS"
},
"details": {"modelId": "dtmi:myModel;1"
}
}
]
}

Notification

Manage Notifications

More information

Get notifications

Get notifications that the current user has the view resource permission on.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "notification1",
"displayName": "Notification1",
"description": "Description",
"broadcast": false,
"trigger": {"alarmTrigger": ["alarmId1",
"alarmId2"
]
},
"channels": {"email": {"active": true,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender1",
"subject": "Any subject"
},
"sms": {"active": false,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender2"
}
},
"workflowId": "workflowID",
"triggerIdentifier": "trigger-identifier",
"subscribers": {"contactGroups": [{"contactGroupId": "contact-group-1"
}
]
}
}
]

Create notification

Create notification requires the notification_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName required	string
description	string or null
trigger required	object
broadcast required	boolean
channels required	object
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

{"trigger": {"alarmTrigger": ["alarmId1"
]
},
"displayName": "Notification1",
"description": "Description",
"broadcast": true,
"channels": {"email": {"active": true,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender1",
"subject": "Any subject"
},
"sms": {"active": true,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender2"
}
},
"organizationId": "organization-1"
}

Response samples

201

Content type

application/json

{"id": "notification1",
"displayName": "Notification1",
"description": "Description",
"broadcast": false,
"trigger": {"alarmTrigger": ["alarmId1",
"alarmId2"
]
},
"channels": {"email": {"active": true,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender1",
"subject": "Any subject"
},
"sms": {"active": false,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender2"
}
},
"workflowId": "workflowID",
"triggerIdentifier": "trigger-identifier",
"subscribers": {"contactGroups": [{"contactGroupId": "contact-group-1"
}
]
}
}

Get notification

Get notification details. The current user must have the view resource permission on the notification.

Authorizations:

bearerAuth

path Parameters

notificationId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "notification1",
"displayName": "Notification1",
"description": "Description",
"broadcast": false,
"trigger": {"alarmTrigger": ["alarmId1",
"alarmId2"
]
},
"channels": {"email": {"active": true,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender1",
"subject": "Any subject"
},
"sms": {"active": false,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender2"
}
},
"workflowId": "workflowID",
"triggerIdentifier": "trigger-identifier",
"subscribers": {"contactGroups": [{"contactGroupId": "contact-group-1"
}
]
}
}

Change notification

Change a Notification. The current user must have the manage resource permission on the Notification.

Authorizations:

bearerAuth

path Parameters

notificationId

required

string

Request Body schema: application/json
required

displayName	string
description	string
trigger	object
broadcast	boolean
channels	object
subscribers	object

Responses

Request samples

Payload

Content type

application/json

{"trigger": {"alarmTrigger": ["alarmId1"
]
},
"displayName": "Notification1",
"description": "Description",
"broadcast": true,
"channels": {"email": {"active": true,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender1",
"subject": "Any subject"
},
"sms": {"active": true,
"template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
"from": "Sender2"
}
},
"organizationId": "organization-1",
"subscribers": {"contactGroups": [{"contactGroupId": "string"
}
]
}
}

Delete notification

Authorizations:

bearerAuth

path Parameters

notificationId

required

string

Responses

Timeseries

Query Timeseries

More information

Get time series

Get time series data. The current user must have the view resource permission on the Assets.

Authorizations:

bearerAuth

Request Body schema: application/json
required

assetId required	string
timeseriesName required	Array of strings
whereClause	string The following column names are allowed: 'time', 'assetid', 'componentid', 'timeseries_name', 'timeseries_type', 'modelid', 'messageid', 'value'.
searchSpanFrom required	string From timestamp in the ISO 8601 format
searchSpanTo required	string To timestamp in the ISO 8601 format
aggregationType	string Enum: "avg" "min" "max" "first" "last" "sum" "median" Type of the aggregation operation
aggregationInterval	string Enum: "PT1M" "PT5M" "PT15M" "PT1H" "PT12H" "P1M" "P1Y" Aggregation will be calculated based on time interval ('PT1M' = '1 minute'). Also endpoint supports custom time intervals e.g. '12 minutes'

Responses

Request samples

Payload

Content type

application/json

{"assetId": "asset1",
"timeseriesName": ["signal1",
"signal2"
],
"whereClause": "timeseries_type = 'telemetry' AND value > 7",
"searchSpanFrom": "2024-03-04 19:03:00.39+00",
"searchSpanTo": "2024-03-10 19:03:00+00",
"aggregationType": "median",
"aggregationInterval": "PT5M"
}

Response samples

200

Content type

application/json

{"items": [{"name": "batterylevel--agg--max",
"signalId": "batterylevel",
"items": [{"value": 244.97301926642587,
"timestamp": "2024-04-01T19:00:00Z"
},
{"value": 21.97301926642587,
"timestamp": "2024-05-01T19:00:00Z"
}
],
"queryResultLimitReached": null
},
{"name": "temperature--agg--max",
"signalId": "temperature",
"items": [{"value": 2.97301926642587,
"timestamp": "2024-04-01T19:00:00Z"
},
{"value": 21.97301926642587,
"timestamp": "2024-06-01T19:00:00Z"
}
],
"queryResultLimitReached": {"resultLimit": 10000
}
}
],
"aggregation": "max",
"time_bucket": "7 minutes"
}

Get last value of specific signal or property

Get last value of specific signal or property. The current user must have the view resource permission on the Assets.

Authorizations:

bearerAuth

Request Body schema: application/json
required

required

Array of objects (TimeseriesGetLastItem)

List of TimeseriesGetLastItem entities

Array

assetId required	string
componentId	string or null
	Array of objects or null (TimeseriesGetLastItemSignal) List of TimeseriesGetLastItemSignal entities

Responses

Request samples

Payload

Content type

application/json

{"items": [{"assetId": "asset1",
"componentId": "component1",
"timeseries": [ ]
},
{"assetId": null,
"componentId": null,
"timeseries": [{"name": "temperature",
"type": "telemetry"
},
{"name": "batterylevel",
"type": "telemetry"
}
]
}
]
}

Response samples

200

Content type

application/json

{"items": [{"time": "2024-03-14 10:37:31.614+00",
"assetId": "asset1",
"componentId": "component1",
"timeseriesName": "reportinterval",
"timeseriesType": "propertyReported",
"value": 7
},
{"time": "2024-03-14 10:38:31.614+00",
"assetId": "asset2",
"componentId": "component2",
"timeseriesName": "batterylevel",
"timeseriesType": "telemetry",
"value": 5.37
}
]
}

Contact Group

Manage Contact Groups

More information

Create contact group

Create contact group requires the contact_group_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName required	string
description	string or null
users	Array of strings
userGroups	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"displayName": "ContactGroup1",
"description": "Description",
"users": ["user1",
"user2"
],
"userGroups": ["group1",
"group2"
],
"organizationId": "organization-1"
}

Response samples

200

Content type

application/json

{"id": "contactgroup1",
"displayName": "ContactGroup1",
"description": "Description",
"users": ["user1",
"user2"
],
"userGroups": ["group1",
"group2"
]
}

Get contact groups

Get all contact groups that the current user has the view resource permission on.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "contactgroup1",
"displayName": "ContactGroup1",
"description": "Description",
"users": ["user1",
"user2"
],
"userGroups": ["group1",
"group2"
]
}
]

Change a contact group

Patch the Contact Group with new displayName or description or userGroups or users. The current user must have the manage resource permission on the Contact Group.

Authorizations:

bearerAuth

path Parameters

contactGroupId

required

string

Request Body schema: application/json
required

displayName	string
description	string or null
users	Array of strings
userGroups	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"displayName": "ContactGroup1",
"description": "Description",
"users": ["user1",
"user2"
],
"userGroups": ["group1",
"group2"
]
}

Get a contact group

Authorizations:

bearerAuth

path Parameters

contactGroupId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "contactgroup1",
"displayName": "ContactGroup1",
"description": "Description",
"users": ["user1",
"user2"
],
"userGroups": ["group1",
"group2"
]
}

Delete contact group

Authorizations:

bearerAuth

path Parameters

contactGroupId

required

string

Responses

Push

Manage SignalR Streams

More information

Negotiate a signalr connection for the authenticated user

Negotiates a signalr connection for the user. Returns a url and access token that can be used to configure the signalr client. The signalR client will need this endpoint.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

{"url": "string",
"accessToken": "string"
}

Add signalR subscription

Adds a subscription for a topic (telemetry , alarm). With an active subscription, updates for the specified assets will be pushed to the signalr service. Subscriptions have a TTL of 600 seconds.

Authorizations:

bearerAuth

Request Body schema: application/json
required

connectionId	string signalr connection id
topic	string Enum: "telemetry" "alarm"
assets	Array of strings
samplingType	string Enum: "none" "first" Sort order: `none` - No sampling `first` - First signal in sampleIntervalSeconds time bucket
sampleIntervalSeconds	integer

Responses

Request samples

Payload

Content type

application/json

{"connectionId": "string",
"topic": "telemetry",
"assets": ["string"
],
"samplingType": "none",
"sampleIntervalSeconds": 0
}

Response samples

200

Content type

application/json

{"id": "string",
"connectionId": "string",
"user": "string",
"topic": "string",
"startTimestamp": "string",
"assets": ["string"
],
"samplingType": "none",
"sampleIntervalSeconds": 0
}

Update signalR subscription

Authorizations:

bearerAuth

path Parameters

subscriptionId

required

string

Subscription Identifier

Request Body schema: application/json
required

connectionId	string signalr connection id
topic	string Enum: "telemetry" "alarm"
assets	Array of strings
samplingType	string Enum: "none" "first" Sort order: `none` - No sampling `first` - First signal in sampleIntervalSeconds time bucket
sampleIntervalSeconds	integer

Responses

Request samples

Payload

Content type

application/json

{"connectionId": "string",
"topic": "telemetry",
"assets": ["string"
],
"samplingType": "none",
"sampleIntervalSeconds": 0
}

Response samples

200

Content type

application/json

{"id": "string",
"connectionId": "string",
"user": "string",
"topic": "string",
"startTimestamp": "string",
"assets": ["string"
],
"samplingType": "none",
"sampleIntervalSeconds": 0
}

Get subscription

Authorizations:

bearerAuth

path Parameters

subscriptionId

required

string

Subscription Identifier

Responses

Response samples

200

Content type

application/json

{"id": "string",
"connectionId": "string",
"user": "string",
"topic": "string",
"startTimestamp": "string",
"assets": ["string"
],
"samplingType": "none",
"sampleIntervalSeconds": 0
}

Delete subscription

Manually delete a subscription for a topic. Note that subscriptions are automatically deleted after 600 seconds from creation.

Authorizations:

bearerAuth

path Parameters

subscriptionId

required

string

Subscription Identifier

Responses

Firmware

Manage Firmware

More information

Upload firmware

Upload firmware file. Upload firmware requires the firmware_management privilege.

Authorizations:

bearerAuth

Request Body schema: multipart/form-data
required

organizationId	string
file	string <binary>

Responses

Response samples

200

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Create release

Сreate release item. Create release requires the firmware_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName required	string
description	string or null
	Array of objects (StartingModel)
	Array of objects (PropertyValue)
organizationId required	string
fileResourceId	string or null
fileName	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Release1",
"description": "Description",
"startingModels": [{"id": "model1",
"displayName": "Model1"
}
],
"propertyValues": [{"key": "key1",
"value": "value1"
}
],
"fileResourceId": "resource1",
"organizationId": "organization-1",
"fileName": "firmware.txt"
}

Response samples

201

Content type

application/json

{"id": "release1",
"displayName": "Release1",
"description": "Description",
"startingModels": [{"id": "model1",
"displayName": "Model1"
}
],
"propertyValues": [{"key": "key1",
"value": "value1"
}
],
"fileResourceId": "resource1"
}

Get releases

Get all releases that the current user has the view resource permission on.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"id": "release1",
"displayName": "Release1",
"description": "Description",
"startingModels": [{"id": "model1",
"displayName": "Model1"
}
],
"propertyValues": [{"key": "key1",
"value": "value1"
}
],
"fileResourceId": "resource1"
}
]

Update release

Put the release with new displayName or description or startingModels or propertyValues. The current user must have the manage resource permission on the Release.

Authorizations:

bearerAuth

path Parameters

releaseId

required

string

Request Body schema: application/json
required

displayName	string
description	string
	Array of objects (StartingModel)
	Array of objects (PropertyValue)
fileResourceId	string
fileName	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Release1",
"description": "Description",
"startingModels": [{"id": "model1",
"displayName": "Model1"
}
],
"propertyValues": [{"key": "key1",
"value": "value1"
}
],
"fileResourceId": "resource1",
"fileName": "firmware.txt"
}

Response samples

200

Content type

application/json

{"id": "release1",
"displayName": "Release1",
"description": "Description",
"startingModels": [{"id": "model1",
"displayName": "Model1"
}
],
"propertyValues": [{"key": "key1",
"value": "value1"
}
],
"fileResourceId": "resource1"
}

Retrieve a release by its unique id

Get Release. The current user must have the view resource permission on the Release.

Authorizations:

bearerAuth

path Parameters

releaseId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "release1",
"displayName": "Release1",
"description": "Description",
"startingModels": [{"id": "model1",
"displayName": "Model1"
}
],
"propertyValues": [{"key": "key1",
"value": "value1"
}
],
"fileResourceId": "resource1"
}

Delete release by its unique id

Delete release by its unique id. The current user must have the delete resource permission on the Release.

Authorizations:

bearerAuth

path Parameters

releaseId

required

string

Responses

Create deployment method template

Сreate Deployment method Template. Create deployment template requires the firmware_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName	string
description	string or null
version	string
	Array of objects (TemplateStep)
	object
organizationId	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Deployment Template 1",
"description": "Description",
"version": "0.0.1",
"steps": [{"name": "FirmwareVersion",
"displayName": "Update Firmware",
"type": "SetProperty",
"value": "1.0.5"
},
{"тame": "RebootRequired",
"displayName": "Reboot Device",
"type": "SetProperty",
"value": "234"
}
],
"status": {"statusPropertyName": "DeploymentStatus",
"statusMap": {"successStatuses": [{"value": "Success"
}
],
"failureStatuses": [{"value": "Failure"
}
],
"rejectStatuses": [{"value": "Rejected"
}
],
"cancelStatuses": [{"value": "Canceled"
}
]
},
"statusType": "ReportedProperty"
},
"organizationId": "organization-1"
}

Response samples

200

Content type

application/json

{"displayName": "Deployment Template 1",
"description": "Description",
"version": "0.0.1",
"steps": [{"name": "FirmwareVersion",
"displayName": "Update Firmware",
"type": "SetProperty",
"value": "1.0.5"
},
{"тame": "RebootRequired",
"displayName": "Reboot Device",
"type": "SetProperty",
"value": "234"
}
],
"status": {"statusPropertyName": "DeploymentStatus",
"statusMap": {"successStatuses": [{"value": "Success"
}
],
"failureStatuses": [{"value": "Failure"
}
],
"rejectStatuses": [{"value": "Rejected"
}
],
"cancelStatuses": [{"value": "Canceled"
}
]
},
"statusType": "ReportedProperty"
},
"templateId": "template1"
}

Get deployment method templates

Get all Deployment method Templates that the current user has the view resource permission on.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"displayName": "Deployment Template 1",
"description": "Description",
"version": "0.0.1",
"steps": [{"name": "FirmwareVersion",
"displayName": "Update Firmware",
"type": "SetProperty",
"value": "1.0.5"
},
{"тame": "RebootRequired",
"displayName": "Reboot Device",
"type": "SetProperty",
"value": "234"
}
],
"status": {"statusPropertyName": "DeploymentStatus",
"statusMap": {"successStatuses": [{"value": "Success"
}
],
"failureStatuses": [{"value": "Failure"
}
],
"rejectStatuses": [{"value": "Rejected"
}
],
"cancelStatuses": [{"value": "Canceled"
}
]
},
"statusType": "ReportedProperty"
},
"templateId": "template1"
}
]

Retrieve a deployment method template by its unique id

Get Deployment method Template. The current user has the view resource permission on Deployment method Template.

Authorizations:

bearerAuth

path Parameters

deploymentTemplateId

required

string

Responses

Response samples

200

Content type

application/json

{"displayName": "Deployment Template 1",
"description": "Description",
"version": "0.0.1",
"steps": [{"name": "FirmwareVersion",
"displayName": "Update Firmware",
"type": "SetProperty",
"value": "1.0.5"
},
{"тame": "RebootRequired",
"displayName": "Reboot Device",
"type": "SetProperty",
"value": "234"
}
],
"status": {"statusPropertyName": "DeploymentStatus",
"statusMap": {"successStatuses": [{"value": "Success"
}
],
"failureStatuses": [{"value": "Failure"
}
],
"rejectStatuses": [{"value": "Rejected"
}
],
"cancelStatuses": [{"value": "Canceled"
}
]
},
"statusType": "ReportedProperty"
},
"templateId": "template1"
}

Delete deployment method template by its unique id

Delete Deployment method Template by its unique id. The current user must have the delete resource permission on the Deployment method Template.

Authorizations:

bearerAuth

path Parameters

deploymentTemplateId

required

string

Responses

Delete provider client FWU instance

Authorizations:

bearerAuth

path Parameters

providerClientId

required

string

Responses

Response samples

200

Content type

application/json

{"deploymentId": "string",
"status": "Ready",
"statusValue": { },
"currentStep": 0,
"logs": [{"timestamp": "string",
"message": "string",
"level": "Error",
"step": 0
}
]
}

Provider client FWU status

Get provider client FWU status

Authorizations:

bearerAuth

path Parameters

providerClientId

required

string

Responses

Response samples

200

Content type

application/json

{"deploymentId": "string",
"status": "Ready",
"statusValue": { },
"currentStep": 0,
"logs": [{"timestamp": "string",
"message": "string",
"level": "Error",
"step": 0
}
]
}

Cancel provider client FWU

Authorizations:

bearerAuth

path Parameters

providerClientId

required

string

Responses

Create deployment

Сreate Deployment. Create deployment requires the firmware_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName required	string
description	string or null
deploymentTemplateId required	string
releaseId required	string
deviceIds required	Array of strings
organizationId required	string

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Deployment 1",
"description": "Description",
"deploymentTemplateId": "deployment-template-1",
"releaseId": "release-1",
"deviceIds": ["device-1",
"device-2"
],
"organizationId": "organization-1"
}

Response samples

201

Content type

application/json

{"deploymentId": "deployment-1",
"displayName": "Deployment 1",
"description": "Description",
"deploymentTemplateId": "deployment-template-1",
"releaseId": "release-1",
"deviceIds": ["device-1",
"device-2"
]
}

Get deployments

Get all Deployments that the current user has the view resource permission on.

Authorizations:

bearerAuth

Responses

Response samples

200

Content type

application/json

[{"deploymentId": "deployment-1",
"displayName": "Deployment 1",
"description": "Description",
"deploymentTemplateId": "deployment-template-1",
"releaseId": "release-1",
"deviceIds": ["device-1",
"device-2"
]
}
]

Retrieve a deployment by its unique id

Get Deployment. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId

required

string

Responses

Response samples

200

Content type

application/json

{"deploymentId": "deployment-1",
"displayName": "Deployment 1",
"description": "Description",
"deploymentTemplateId": "deployment-template-1",
"releaseId": "release-1",
"deviceIds": ["device-1",
"device-2"
]
}

Update specific fields of a deployment

Patch the deployment with new displayName or description or deploymentTemplateId or releaseId or deviceIds. The current user must have the manage resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId

required

string

Request Body schema: application/json
required

displayName	string
description	string or null
deploymentTemplateId	string
releaseId	string
deviceIds	Array of strings

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Deployment 1",
"description": "Description",
"deploymentTemplateId": "deployment-template-1",
"releaseId": "release-1",
"deviceIds": ["device-1",
"device-2"
]
}

Response samples

200

Content type

application/json

{"deploymentId": "deployment-1",
"displayName": "Deployment 1",
"description": "Description",
"deploymentTemplateId": "deployment-template-1",
"releaseId": "release-1",
"deviceIds": ["device-1",
"device-2"
]
}

Delete deployment by its unique id

Delete deployment by its unique id. The current user must have the delete resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId

required

string

Responses

Retrieve a deployment status by its unique id

Get Deployment status. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId

required

string

Responses

Response samples

200

Content type

application/json

{"id": "deployment-12345",
"aggregateStatus": "Succeeded",
"fwuStatusCounts": {"succeeded": 10,
"failed": 2,
"running": 3,
"rejected": 1,
"canceled": 0,
"ready": 5
},
"startTimestamp": "2025-06-12T09:36:34.7493006+00:00",
"endTimestamp": "2025-06-12T09:36:34.7941229+00:00",
"providerClientStatuses": [{"providerClientId": "client-001",
"status": "Succeeded",
"statusValue": {"details": "Firmware updated successfully"
},
"currentStep": 5,
"currentStepTimestamp": "2025-05-19T08:30:00Z"
}
]
}

Retrieve a deployment device status by deployment id and device id

Get Deployment device status. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId required	string
deviceId required	string

Responses

Response samples

200

Content type

application/json

{"deploymentId": "string",
"status": "Ready",
"statusValue": { },
"currentStep": 0,
"logs": [{"timestamp": "string",
"message": "string",
"level": "Error",
"step": 0
}
]
}

Cancel a deployment device processing by deployment id and device id

Cancel Deployment device run. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId required	string
deviceId required	string

Responses

Response samples

200

Content type

application/json

{"status": "Ready"
}

Cancel a deployment processing by deployment id

Cancel Deployment run. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId

required

string

Responses

Response samples

200

Content type

application/json

{"status": "Ready"
}

Restart a deployment device processing by deployment id and device id

Restart Deployment device run. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId required	string
deviceId required	string

Responses

Response samples

200

Content type

application/json

{"status": "Ready"
}

Restart a deployment processing by deployment id

Restart Deployment run. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId

required

string

Responses

Response samples

200

Content type

application/json

{"status": "Ready"
}

Get statuses of the list of deployments

Get Deployments statuses

Authorizations:

bearerAuth

Request Body schema: application/json
required

ids

required

Array of strings

Responses

Request samples

Payload

Content type

application/json

{"ids": ["string"
]
}

Response samples

200

Content type

application/json

[{"id": "deployment-12345",
"aggregateStatus": "Succeeded",
"fwuStatusCounts": {"succeeded": 10,
"failed": 2,
"running": 3,
"rejected": 1,
"canceled": 0,
"ready": 5
},
"startTimestamp": "2025-06-12T09:36:34.7493006+00:00",
"endTimestamp": "2025-06-12T09:36:34.7941229+00:00",
"providerClientStatuses": [{"providerClientId": "client-001",
"status": "Succeeded",
"statusValue": {"details": "Firmware updated successfully"
},
"currentStep": 5,
"currentStepTimestamp": "2025-05-19T08:30:00Z"
}
]
}
]

Start deployment process by unique id of the Deployment

Start Deployment. The current user must have the view resource permission on the Deployment.

Authorizations:

bearerAuth

path Parameters

deploymentId

required

string

Responses

Response samples

200

Content type

application/json

{"status": "Ready"
}

OrgTemplate

Retrieve a list of all organization templates

Get all organization templates that the current user has the view resource permission on (Supports filtering by tags).

Authorizations:

bearerAuth

query Parameters

limit

integer

Number of items to retrieve (max: appsetting {ResponseEntitiesLimit})

tag

Array of strings

Examples:

- Example without tag (route /orgTemplates)
tag=department:sales - Example with a single tag (route /orgTemplates?tag=department:sales)
tag=department:sales,status:active - Example with multiple tags and 'AND' conditions (route /orgTemplates?tag=department:sales&tag=status:active)
tag=department:sales|marketing - Example with multiple 'OR' conditions for tag values (route /orgTemplates?tag=department:sales|marketing)
tag=department:sales|marketing,status:active|draft - Example with 'OR' and 'AND' conditions (route /orgTemplates?tag=department:sales|marketing&tag=status:active|draft)

Filter by tags (possible to filter by single tag or multiple using AND and OR conditions)

Responses

Response samples

200

Content type

application/json

{"items": [{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { }
}
],
"responseEntitiesLimitReached": {"resultLimit": 0
}
}

Create a new organization template

Create resource with JSON document requires the organization_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

displayName required	string
description	string or null
	object
document required	object
organizationId required	string
metadata	object or null
history	object or null

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Project Plan",
"description": "Detailed project plan for Q4.",
"tags": {"department": "sales",
"status": "draft"
},
"document": {"sections": [{"title": "Introduction",
"content": "This is the introduction section of the project plan."
},
{"title": "Objectives",
"content": "The objectives of this project are..."
}
]
},
"organizationId": "organization1",
"metadata": {"category": "template",
"version": "1.0"
},
"history": [{"timestamp": "2025-11-01T10:00:00Z",
"action": "created",
"user": "admin@example.com"
}
]
}

Response samples

201

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Update specific fields of a organization template

Patch the organization template with new displayName or description or tags or document. The current user must have the manage resource permission on the OrgTemplate.

Authorizations:

bearerAuth

path Parameters

orgTemplateId

required

string

Request Body schema: application/json
required

displayName	string or null
description	string or null
	object or null
document	object or null
metadata	object or null
history	object or null

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Project Plan",
"description": "Detailed project plan for Q4.",
"tags": {"department": "sales",
"status": "draft"
},
"document": {"sections": [{"title": "Introduction",
"content": "This is the introduction section of the project plan."
},
{"title": "Objectives",
"content": "The objectives of this project are..."
}
]
},
"metadata": {"category": "documentation",
"version": "1.1"
},
"history": [{"timestamp": "2025-10-01T10:00:00Z",
"action": "created",
"user": "user@example.com"
},
{"timestamp": "2025-10-02T14:30:00Z",
"action": "updated",
"user": "admin@example.com"
}
]
}

Response samples

200

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Retrieve a organization template by its unique id

Get Organization Template. The current user must have the view resource permission on the OrgTemplate.

Authorizations:

bearerAuth

path Parameters

orgTemplateId

required

string

Responses

Response samples

200

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Delete organization template by its unique id

Delete organization template by its unique id. The current user must have the delete resource permission on the OrgTemplate.

Authorizations:

bearerAuth

path Parameters

orgTemplateId

required

string

Responses

Resource

Retrieve a list of all resources

Get all resources that the current user has the view resource permission on (Supports filtering by resource_type and tags).

Authorizations:

bearerAuth

query Parameters

limit	integer Number of items to retrieve (max: appsetting {ResponseEntitiesLimit})
resource_type	string Filter by resource type. Valid resource types: ['user-resource']
tag	Array of strings Examples: - Example without tag (route /resources) tag=department:sales - Example with a single tag (route /resources?tag=department:sales) tag=department:sales,status:active - Example with multiple tags and 'AND' conditions (route /resources?tag=department:sales&tag=status:active) tag=department:sales\|marketing - Example with multiple 'OR' conditions for tag values (route /resources?tag=department:sales\|marketing) tag=department:sales\|marketing,status:active\|draft - Example with 'OR' and 'AND' conditions (route /resources?tag=department:sales\|marketing&tag=status:active\|draft) Filter by tags (possible to filter by single tag or multiple using AND and OR conditions)

Responses

Response samples

200

Content type

application/json

{"items": [{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { }
}
],
"responseEntitiesLimitReached": {"resultLimit": 0
}
}

Create a new resource

Create resource with JSON document requires the resource_item_management privilege.

Authorizations:

bearerAuth

Request Body schema: application/json
required

resource_type required	string Value: "user-resource"
displayName required	string
description	string or null
	object
document required	object
organizationId required	string
metadata	object or null
history	object or null

Responses

Request samples

Payload

Content type

application/json

{"resource_type": "user-resource",
"displayName": "Project Plan",
"description": "Detailed project plan for Q4.",
"tags": {"department": "sales",
"status": "draft"
},
"document": {"sections": [{"title": "Introduction",
"content": "This is the introduction section of the project plan."
},
{"title": "Objectives",
"content": "The objectives of this project are..."
}
]
},
"organizationId": "organization1",
"metadata": {"category": "documentation",
"version": "1.0"
},
"history": [{"timestamp": "2025-10-01T10:00:00Z",
"action": "created",
"user": "user@example.com"
}
]
}

Response samples

201

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Update specific fields of a resource

Patch the resource with new displayName or description or tags or document. The current user must have the manage resource permission on the Resource.

Authorizations:

bearerAuth

path Parameters

resourceId

required

string

Request Body schema: application/json
required

displayName	string or null
description	string or null
	object or null
document	object or null
metadata	object or null
history	object or null

Responses

Request samples

Payload

Content type

application/json

{"displayName": "Project Plan",
"description": "Detailed project plan for Q4.",
"tags": {"department": "sales",
"status": "draft"
},
"document": {"sections": [{"title": "Introduction",
"content": "This is the introduction section of the project plan."
},
{"title": "Objectives",
"content": "The objectives of this project are..."
}
]
},
"metadata": {"category": "documentation",
"version": "1.1"
},
"history": [{"timestamp": "2025-10-01T10:00:00Z",
"action": "created",
"user": "user@example.com"
},
{"timestamp": "2025-10-02T14:30:00Z",
"action": "updated",
"user": "admin@example.com"
}
]
}

Response samples

200

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Retrieve a resource by its unique id

Get Resource metadata. The current user must have the view resource permission on the Resource.

Authorizations:

bearerAuth

path Parameters

resourceId

required

string

Responses

Response samples

200

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Delete resource by its unique id

Delete resource by its unique id. The current user must have the delete resource permission on the Resource.

Authorizations:

bearerAuth

path Parameters

resourceId

required

string

Responses

Create a new resource

Create resource with binary file data requires the resource_item_management privilege.

Authorizations:

bearerAuth

Request Body schema: multipart/form-data
required

resource_type required	string Value: "user-resource"
displayName required	string
description	string or null
file required	string <binary>
organizationId required	string
	object or null
metadata	object or null
history	object or null

Responses

Response samples

201

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Reupload a resource file

Reupload a resource file. The current user must have the manage resource permission on the Resource.

Authorizations:

bearerAuth

path Parameters

resourceId

required

string

Request Body schema: multipart/form-data
required

file required	string <binary>
organizationId required	string
	object or null
metadata	object or null
history	object or null

Responses

Response samples

200

Content type

application/json

{"resource_type": "string",
"id": "string",
"displayName": "string",
"description": "string",
"tags": {"property1": "string",
"property2": "string"
},
"document": { },
"originalFileName": "string",
"fileUrl": "string",
"metadata": { },
"history": { }
}

Download a resource file

Download a Resource file. The current user must have the view resource permission on the Resource.

Authorizations:

bearerAuth

path Parameters

resourceId

required

string

Responses

Retrieve a list of all resources tags or tags related to specific resource types

Get resources tags that the current user has the view resource permission on (Supports filtering by resource_type).

Authorizations:

bearerAuth

query Parameters

resource_type

Array of strings

Filter by resource type. Valid resource types: ['user-resource']

Responses

Response samples

200

Content type

application/json

{"tags": [{"key": "string",
"value": "string"
}
]
}

Add/Modify/Delete tags in a resource identified by {resourceId}

Add/Modify/Delete tags. The current user must have the manage resource permission on the Resource.

Authorizations:

bearerAuth

path Parameters

resourceId

required

string

Request Body schema: application/json
required

object

property name*

additional property

string

Responses

Request samples

Payload

Content type

application/json

{"tags": {"property1": "string",
"property2": "string"
}
}

Response samples

200

Content type

application/json

{"resource_id": "string",
"tags": [{"key": "string",
"value": "string"
}
]
}

Beacontower Core (1.0.11)

Authentication

Get a Access Token (JWT)

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Provider

Get Providers

Authorizations:

query Parameters

Responses

Response samples

Create Provider

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Create or update an existing Provider

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Get provider by ID

Authorizations:

path Parameters

Responses

Response samples

Deletes a provider

Authorizations:

path Parameters

Responses

ProviderClient

Get Clients

Authorizations:

path Parameters

Responses

Response samples

Create Client

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Get Client

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Delete Client

Authorizations:

path Parameters

Responses

Update Client properties

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Provisions a provider client onto it's provider infrastructure

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Unprovisions a provider client from it's provider infrastructure

Authorizations:

path Parameters

Responses

Run direct method command

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Get reported properties

Authorizations:

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required