Digital Twin Registry API (v2)

Download OpenAPI specification:Download

The Single Point of Information about the existence of Twins and their Aspects. It is the primary means for any consumer to handle Twins.

Also see Bulk API and Statistics API.

Authentication

The API offers currently one form of authentication:

  • OAuth2 - An open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.

Digital Twin

Lists or queries Twins with cursor pagination

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

query Parameters
select
string

Define an RQL select option, read more

filter
string

Define an RQL filter query, read more

option
string

Define an RQL sort option, read more

cursor
string
Default: "0"

the cursor used for pagination.

limit
integer <int32> [ 0 .. 500 ]
Default: 500

the size of the requested page. Defaults to 500 if omitted. Maximum allowed value is 500.

Responses

Request samples

# List all DTs for the tenant

curl -X GET 'https://.../{tenantId}/twins/' \
  -H 'Authorization: bearer {token}' -H 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string",
  • "itemCount": 0
}

Registers a Twin

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Digitial Twin object which will added to the registry.

twinType
string <= 128 characters

The type of the Twin

twinCategory
string <= 128 characters

The category of the Twin

description
string <= 4000 characters

Detailed description of the Twin

manufacturer
string <= 128 characters

Manufacturer of the physical asset represented by the Twin

required
Array of objects (LocalIdentifierCreateDto) [ 1 .. 10 ] items unique

Local Identifiers of the Twin

labels
Array of strings <= 10 items unique

Labels of the Twin

groups
Array of integers <int64> (EntityId) <= 50 items unique [ items <int64 > ]

Twin Groups in which the Twin shall be a member.

twinKind
string (DigitalTwinKindDto)
Enum: "TYPE" "INSTANCE" "ROLE" "NOT_APPLICABLE"

Kind of the Twin

Responses

Request samples

Content type
application/json
{
  • "twinType": "Bosch Nexo cordless Wi-Fi nutrunner",
  • "twinCategory": "Drill",
  • "description": "On Nexo the complete control unit is in the nutrunner – the first of its kind.",
  • "manufacturer": "Bosch",
  • "localIdentifiers": [
    ],
  • "labels": [
    ],
  • "groups": [
    ],
  • "twinKind": "INSTANCE"
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "twinType": "Bosch Nexo cordless Wi-Fi nutrunner",
  • "twinCategory": "Drill",
  • "description": "On Nexo the complete control unit is in the nutrunner – the first of its kind.",
  • "manufacturer": "Bosch",
  • "createdAt": 1683797815385,
  • "aspects": [
    ],
  • "localIdentifiers": [
    ],
  • "labels": [
    ],
  • "groups": [
    ],
  • "twinKind": "INSTANCE"
}

Gets a Twin

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Responses

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "twinType": "Bosch Nexo cordless Wi-Fi nutrunner",
  • "twinCategory": "Drill",
  • "description": "On Nexo the complete control unit is in the nutrunner – the first of its kind.",
  • "manufacturer": "Bosch",
  • "createdAt": 1683797815385,
  • "aspects": [
    ],
  • "localIdentifiers": [
    ],
  • "labels": [
    ],
  • "groups": [
    ],
  • "twinKind": "INSTANCE"
}

Deletes a Twin

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Responses

Merge a Twin

Performs a partial update on the Twin. Only properties present in the payload will be updated, all other properties will be left intact.
All lists e.g. Labels, Local Identifiers etc. denotes the desired target state (if present).
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Request Body schema: application/json
required

Digitial Twin object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386

Array of objects or null (LocalIdentifierReplaceDto) <= 10 items unique

Local Identifiers of the Twin

groups
Array of integers or null <int64> <= 50 items unique

Twin Groups in which the Twin will become a member. When adding or removing null or empty groups via listOperator, the operation has no impact on the Twin's groups.

twinType
string or null <= 128 characters

The type of the Twin

twinCategory
string or null <= 128 characters

The category of the Twin

description
string or null <= 4000 characters

Detailed description of the Twin

manufacturer
string or null <= 128 characters

Manufacturer of the physical asset represented by the Twin

labels
Array of strings or null <= 10 items unique

Labels of the Twin. Denotes the target state. Any labels already present on the Twin and not listed here will be deleted.

listOperator
required
string (ListOperator)
Default: "replace"
Enum: "replace" "add" "remove"

Operator to specify the kind of operation to perform on lists given within the body. Add/Remove operations featuring null or empty values produce no effect. Add/Remove operator adds / removes a single element. Replace replaces the entire list.

twinKind
string or null
Enum: "TYPE" "INSTANCE" "ROLE" "NOT_APPLICABLE"

Kind of the Twin

Responses

Request samples

Content type
application/json
{
  • "localIdentifiers": [
    ],
  • "groups": [
    ],
  • "twinType": "Bosch Nexo cordless Wi-Fi nutrunner",
  • "twinCategory": "Drill",
  • "description": "On Nexo the complete control unit is in the nutrunner – the first of its kind.",
  • "manufacturer": "Bosch",
  • "labels": [
    ],
  • "listOperator": "replace",
  • "twinKind": "INSTANCE"
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "twinType": "Bosch Nexo cordless Wi-Fi nutrunner",
  • "twinCategory": "Drill",
  • "description": "On Nexo the complete control unit is in the nutrunner – the first of its kind.",
  • "manufacturer": "Bosch",
  • "createdAt": 1683797815385,
  • "aspects": [
    ],
  • "localIdentifiers": [
    ],
  • "labels": [
    ],
  • "groups": [
    ],
  • "twinKind": "INSTANCE"
}

Local Identifier

Creates a Local Identifier

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Request Body schema: application/json
required

Local identifier object which will added to the registry.

required
Array of objects (LocalIdentifierKeyPairCreateReplaceDto) [ 1 .. 5 ] items unique

Responses

Request samples

Content type
application/json
{
  • "localIdentifierKeyPairs": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "localIdentifierKeyPairs": [
    ],
  • "hash": "string"
}

Replace a Local Identifier

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

localIdentifierId
required
integer <int64>

The ID of the Local Identifier being updated.

Request Body schema: application/json
required

Local identifier for update.

required
Array of objects (LocalIdentifierKeyPairCreateReplaceDto) [ 1 .. 5 ] items unique

Responses

Request samples

Content type
application/json
{
  • "localIdentifierKeyPairs": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "localIdentifierKeyPairs": [
    ],
  • "hash": "string"
}

Deletes a Local Identifier

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

localIdentifierId
required
integer <int64>

The ID of the Local Identifier being deleted.

Responses

Aspect

Creates an Aspect

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

Request Body schema: application/json
required

Aspect object which will added to the registry.

required
object (ModelReferenceCreateReplaceDto)

Model reference of the Aspect

required
Array of objects (HttpEndpointCreateDto) unique

HTTP endpoints of the Aspect

Array of objects (MqttEndpointCreateDto) unique

MQTT endpoint of the Aspect

Responses

Request samples

Content type
application/json
{
  • "modelReference": {
    },
  • "httpEndpoints": [],
  • "mqttEndpoints": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "modelReference": {
    },
  • "httpEndpoints": [],
  • "mqttEndpoints": [
    ]
}

Retrieves an Aspect

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect.

Responses

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "modelReference": {
    },
  • "httpEndpoints": [],
  • "mqttEndpoints": [
    ]
}

Replace an Aspect

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect being updated.

Request Body schema: application/json
required

Aspect update object for update.

required
object (ModelReferenceCreateReplaceDto)

Model reference of the Aspect

required
Array of objects (HttpEndpointReplaceDto) unique

HTTP endpoints of the Aspect

Array of objects (MqttEndpointReplaceDto) unique

MQTT endpoint of the Aspect

Responses

Request samples

Content type
application/json
{
  • "modelReference": {
    },
  • "httpEndpoints": [],
  • "mqttEndpoints": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "modelReference": {
    },
  • "httpEndpoints": [],
  • "mqttEndpoints": [
    ]
}

Deletes an Aspect

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect being deleted.

Responses

Merge an Aspect

Performs a partial update on the Aspect. Only properties present in the payload will be updated, all other properties will be left intact.
All lists e.g. Labels, Local Identifiers etc. denotes the desired target state (if present).
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect being deleted.

Request Body schema: application/json
required

Aspect object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386

object or null (ModelReferenceMergeDto)

Model reference of the Aspect

Array of objects or null (HttpEndpointReplaceDto) unique

HTTP endpoints of the Aspect

Array of objects or null (MqttEndpointReplaceDto) unique

MQTT endpoint of the Aspect

listOperator
string (ListOperator)
Default: "replace"
Enum: "replace" "add" "remove"

Operator to specify the kind of operation to perform on lists given within the body. Add/Remove operations featuring null or empty values produce no effect. Add/Remove operator adds / removes a single element. Replace replaces the entire list.

Responses

Request samples

Content type
application/json
{
  • "modelReference": {
    },
  • "httpEndpoints": [],
  • "mqttEndpoints": [
    ],
  • "listOperator": "replace"
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "modelReference": {
    },
  • "httpEndpoints": [],
  • "mqttEndpoints": [
    ]
}

Aspect HTTP Endpoint

Creates a HTTP Endpoint

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect for which the HttpEndpoint is created.

Request Body schema: application/json
required

HTTP Endpoint object which will added to the registry.

url
required
string [ 1 .. 2000 ] characters

The URL of the endpoint, preferably unencoded. Will be stored exactly as given.

subprotocolBody
string [ 1 .. 2048 ] characters

Subprotocol body used for AAS mapping. Only valid for EndpointType DSP.

type
required
string (HttpEndpointType) [ 1 .. 20 ] characters
Enum: "READ" "FILTER" "OPERATIONS" "DSP"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Partially update HTTP Endpoint

Performs a partial update on a HTTP Endpoint.
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect which the HttpEndpoint being deleted belongs to.

httpEndpointId
required
integer <int64>

The ID of the HTTP Endpoint being updated.

Request Body schema: application/json
required

HTTP Endpoint object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386.

url
string or null [ 1 .. 2000 ] characters

The URL of the endpoint, preferably unencoded. Will be stored exactly as given.

subprotocolBody
string or null [ 1 .. 2048 ] characters

Subprotocol body used for AAS mapping. Only valid for EndpointType DSP.

type
string or null [ 1 .. 20 ] characters
Enum: "READ" "FILTER" "OPERATIONS" "DSP"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Deletes a HTTP Endpoint

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect which the HttpEndpoint being deleted belongs to.

httpEndpointId
required
integer <int64>

The ID of the HttpEndpoint being deleted.

Responses

Aspect MQTT Endpoint

Creates a MQTT Endpoint

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect for which the MqttEndpoint is created.

Request Body schema: application/json
required

MQTT Endpoint object which will added to the registry.

brokerAddress
required
string (BrokerAddress) [ 1 .. 2000 ] characters ^(mqtt://|mqtts://|tcp://|ssl://).*

Address of the broker, preferably unencoded. Will be stored exactly as given.

responseTopicName
required
string [ 1 .. 400 ] characters

The topic name of the MqttEndpoint for responses

requestTopicName
string [ 1 .. 400 ] characters

The topic name of the MqttEndpoint for requests. Use only for endpoint type operations! Will be ignored otherwise.

type
required
string (MqttEndpointType) [ 1 .. 4 ] characters
Enum: "READ" "OPERATIONS"

Responses

Request samples

Content type
application/json
{
  • "brokerAddress": "tcp://broker.mqttdashboard.com:1883",
  • "responseTopicName": "errors",
  • "requestTopicName": "errors",
  • "type": "READ"
}

Response samples

Content type
application/json
{
  • "brokerAddress": "tcp://broker.mqttdashboard.com:1883",
  • "responseTopicName": "errors",
  • "requestTopicName": "errors",
  • "id": "5821L",
  • "type": "READ"
}

Partially update MQTT Endpoint

Performs a partial update on a MQTT Endpoint.
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect which the MqttEndpoint being deleted belongs to.

mqttEndpointId
required
integer <int64>

The ID of the MQTT Endpoint being updated.

Request Body schema: application/json
required

MQTT Endpoint object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386.

brokerAddress
string or null [ 1 .. 2000 ] characters ^(mqtt://|mqtts://|tcp://|ssl://).*

Address of the broker, preferably unencoded. Will be stored exactly as given.

responseTopicName
string or null [ 1 .. 400 ] characters

The topic name of the MqttEndpoint for responses

requestTopicName
string or null [ 1 .. 400 ] characters

The topic name of the MqttEndpoint for requests. Use only for endpoint type operations! Will be ignored otherwise.

type
string or null [ 1 .. 4 ] characters
Enum: "READ" "OPERATIONS"

Responses

Request samples

Content type
application/json
{
  • "brokerAddress": "tcp://broker.mqttdashboard.com:1883",
  • "responseTopicName": "errors",
  • "requestTopicName": "errors",
  • "type": "READ"
}

Response samples

Content type
application/json
{
  • "brokerAddress": "tcp://broker.mqttdashboard.com:1883",
  • "responseTopicName": "errors",
  • "requestTopicName": "errors",
  • "id": "5821L",
  • "type": "READ"
}

Deletes a MQTT Endpoint

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

twinId
required
integer <int64>

Unique identifier of the Twin.

aspectId
required
integer <int64>

The ID of the Aspect from which the MqttEndpoint is removed.

mqttEndpointId
required
integer <int64>

The ID of the MqttEndpoint being deleted.

Responses

Digital Twin Group

List or query for Twin Groups with cursor pagination

If no query string is given, retrieves all Twin Groups for the tenant. If a query string is given, this is a RQL query on Twin Group properties. By default the page size is limited to 500 items. The maximum page size is limited to 500 items.

Example RQL queries:

filter=eq(name, "Group")
filter=in(id, 1, 2, 3)

More information about RQL usage in Digital Twin Registry can be found in the Documentation.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

query Parameters
select
string

Define an RQL select option, read more

filter
string

Define an RQL filter query, read more

option
string

Define an RQL sort option, read more

cursor
string
Default: "0"

the cursor used for pagination.

limit
integer <int32> [ 0 .. 500 ]
Default: 500

the size of the requested page. Defaults to 500 if omitted. Maximum allowed value is 500.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string",
  • "itemCount": 0
}

Create a new Twin Group

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Digitial Twin Group object which will added to the registry.

name
required
string <= 128 characters

Human-readable and unique name of the Twin Group

description
string <= 4000 characters

Detailed description of the Twin Group

Responses

Request samples

Content type
application/json
{
  • "name": "Drills",
  • "description": "All drills"
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Drills",
  • "description": "All drills",
  • "aspectTemplates": [
    ]
}

Get Twin Group by ID

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

groupId
required
integer <int64>

The ID of the requested Twin Group.

Responses

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Drills",
  • "description": "All drills",
  • "aspectTemplates": [
    ]
}

Delete Twin Group

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

groupId
required
integer <int64>

The ID of the Twin Group being deleted.

Responses

Partially update Twin Group

Performs a partial update on a Twin Group.
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

groupId
required
integer <int64>

The ID of the Twin Group being updated.

Request Body schema: application/json
required

Digitial Twin Group object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386

name
string or null <= 128 characters

Human-readable and unique name of the Twin Group

description
string or null <= 4000 characters

Detailed description of the Twin Group

listOperator
string (ListOperator)
Default: "replace"
Enum: "replace" "add" "remove"

Operator to specify the kind of operation to perform on lists given within the body. Add/Remove operations featuring null or empty values produce no effect. Add/Remove operator adds / removes a single element. Replace replaces the entire list.

Responses

Request samples

Content type
application/json
{
  • "name": "Drills",
  • "description": "All drills",
  • "listOperator": "replace"
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Drills",
  • "description": "All drills",
  • "aspectTemplates": [
    ]
}

Replace existing Twin Group

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

groupId
required
integer <int64>

The ID of the Twin Group being updated.

Request Body schema: application/json
required

Digitial Twin Group object which will repalced to the registry.

name
required
string <= 128 characters

Human-readable and unique name of the Twin Group

description
string <= 4000 characters

Detailed description of the Twin Group

Responses

Request samples

Content type
application/json
{
  • "name": "Drills",
  • "description": "All drills"
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Drills",
  • "description": "All drills",
  • "aspectTemplates": [
    ]
}

Aspect Template

Get Aspect Template by ID

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the requested Aspect Template.

Responses

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Movement aspect template",
  • "modelReference": {
    },
  • "httpEndpointTemplates": [],
  • "mqttEndpointTemplates": [
    ],
  • "groups": [
    ]
}

Delete Aspect Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template being deleted.

Responses

Partially update Aspect Template

Performs a partial update on an Aspect Template.
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template being updated.

Request Body schema: application/json
required

Aspect Template object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386

name
string or null [ 1 .. 128 ] characters

Human-readable and unique name of the Aspect Template

object or null (ModelReferenceMergeDto)

Model reference of the Aspect

groups
Array of integers or null <int64> (EntityId) <= 50 items unique

Twin Groups to which the Aspect Template is assigned.

listOperator
string (ListOperator)
Default: "replace"
Enum: "replace" "add" "remove"

Operator to specify the kind of operation to perform on lists given within the body. Add/Remove operations featuring null or empty values produce no effect. Add/Remove operator adds / removes a single element. Replace replaces the entire list.

Responses

Request samples

Content type
application/json
{
  • "name": "Movement aspect template",
  • "modelReference": {
    },
  • "groups": [
    ],
  • "listOperator": "replace"
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Movement aspect template",
  • "modelReference": {
    },
  • "httpEndpointTemplates": [],
  • "mqttEndpointTemplates": [
    ],
  • "groups": [
    ]
}

Replace existing Aspect Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template being updated.

Request Body schema: application/json
required

Aspect Template object which will replace to the registry.

name
required
string [ 1 .. 128 ] characters

Human-readable and unique name of the Aspect Template

required
object (ModelReferenceCreateReplaceDto)

Model reference of the Aspect

required
Array of objects (HttpEndpointTemplateCreateDto) unique

HTTP endpoint templates of the Aspect. Currently ignored for the PUT replacement.

Array of objects (MqttEndpointTemplateCreateDto) unique

MQTT endpoint templates of the Aspect. Currently ignored for the PUT replacement.

groups
Array of integers <int64> (EntityId) <= 50 items unique [ items <int64 > ]

Twin Groups to which the Aspect Template is assigned.

Responses

Request samples

Content type
application/json
{
  • "name": "Movement aspect template",
  • "modelReference": {
    },
  • "httpEndpointTemplates": [],
  • "mqttEndpointTemplates": [
    ],
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Movement aspect template",
  • "modelReference": {
    },
  • "httpEndpointTemplates": [],
  • "mqttEndpointTemplates": [
    ],
  • "groups": [
    ]
}

Lists or queries Aspect Templates with cursor pagination

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

query Parameters
select
string

Define an RQL select option, read more

filter
string

Define an RQL filter query, read more

option
string

Define an RQL sort option, read more

cursor
string
Default: "0"

the cursor used for pagination.

limit
integer <int32> [ 0 .. 500 ]
Default: 500

the size of the requested page. Defaults to 500 if omitted. Maximum allowed value is 500.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string",
  • "itemCount": 0
}

Create a new Aspect Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

Request Body schema: application/json
required

Aspect Template object which will add to the registry.

name
required
string [ 1 .. 128 ] characters

Human-readable and unique name of the Aspect Template

required
object (ModelReferenceCreateReplaceDto)

Model reference of the Aspect

required
Array of objects (HttpEndpointTemplateCreateDto) unique

HTTP endpoint templates of the Aspect. Currently ignored for the PUT replacement.

Array of objects (MqttEndpointTemplateCreateDto) unique

MQTT endpoint templates of the Aspect. Currently ignored for the PUT replacement.

groups
Array of integers <int64> (EntityId) <= 50 items unique [ items <int64 > ]

Twin Groups to which the Aspect Template is assigned.

Responses

Request samples

Content type
application/json
{
  • "name": "Movement aspect template",
  • "modelReference": {
    },
  • "httpEndpointTemplates": [],
  • "mqttEndpointTemplates": [
    ],
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5821L",
  • "name": "Movement aspect template",
  • "modelReference": {
    },
  • "httpEndpointTemplates": [],
  • "mqttEndpointTemplates": [
    ],
  • "groups": [
    ]
}

HTTP Endpoint Template

Create a new HTTP Endpoint Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

Unique identifier of the Aspect Template

Request Body schema: application/json
required

HTTP Endpoint Template object which will add to the registry.

urlTemplate
required
string (HttpUrlTemplate) [ 1 .. 2000 ] characters

The URL template of the endpoint, exactly as it was given when the HttpEndpoint was stored. Clients have to take care of any encoding that might have been applied before. Template parameters take the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

subprotocolBodyTemplate
string (SubprotocolBodyTemplate) [ 1 .. 2048 ] characters

Subprotocol body used for AAS mapping. Only valid for EndpointType DSP.

type
required
string (HttpEndpointType) [ 1 .. 20 ] characters
Enum: "READ" "FILTER" "OPERATIONS" "DSP"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Delete HTTP Endpoint Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template.

id
required
integer <int64>

The ID of the HTTP Endpoint Template that is being deleted.

Responses

Partially update HTTP Endpoint Template

Performs a partial update on a HTTP Endpoint Template. The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template.

id
required
integer <int64>

The ID of the HTTP Endpoint Template being updated.

Request Body schema: application/json
required

HTTP Endpoint Template object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386

urlTemplate
string or null [ 1 .. 2000 ] characters

The URL template of the endpoint, exactly as it was given when the HttpEndpoint was stored. Clients have to take care of any encoding that might have been applied before. Template parameters take the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

subprotocolBodyTemplate
string or null [ 1 .. 2048 ] characters

Subprotocol body used for AAS mapping. Only valid for EndpointType DSP.

type
string or null [ 1 .. 20 ] characters
Enum: "READ" "FILTER" "OPERATIONS" "DSP"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

HTTP Endpoint Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template being updated.

id
required
integer <int64>

The ID of the HTTP Endpoint Template being updated.

Request Body schema: application/json
required

HTTP Endpoint Template object which will replace to the registry.

urlTemplate
required
string (HttpUrlTemplate) [ 1 .. 2000 ] characters

The URL template of the endpoint, exactly as it was given when the HttpEndpoint was stored. Clients have to take care of any encoding that might have been applied before. Template parameters take the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

subprotocolBodyTemplate
string (SubprotocolBodyTemplate) [ 1 .. 2048 ] characters

Subprotocol body used for AAS mapping. Only valid for EndpointType DSP.

type
required
string (HttpEndpointType) [ 1 .. 20 ] characters
Enum: "READ" "FILTER" "OPERATIONS" "DSP"

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

MQTT Endpoint Template

Create a new MQTT Endpoint Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

Unique identifier of the Aspect Template

Request Body schema: application/json
required

MQTT Endpoint Template object which will add to the registry.

brokerAddressTemplate
required
string (BrokerAddressTemplate) [ 1 .. 2000 ] characters ^(mqtt://|mqtts://|tcp://|ssl://).*

Address template of the broker, preferably unencoded. Will be stored exactly as given. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

responseTopicNameTemplate
required
string (TopicNameTemplate) [ 1 .. 400 ] characters

A template for the topic name of the MqttEndpoint. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

requestTopicNameTemplate
string (TopicNameTemplate) [ 1 .. 400 ] characters

A template for the topic name of the MqttEndpoint. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

type
required
string (MqttEndpointType) [ 1 .. 4 ] characters
Enum: "READ" "OPERATIONS"

Responses

Request samples

Content type
application/json
{
  • "brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
  • "responseTopicNameTemplate": "twins/${twin_id}/status",
  • "requestTopicNameTemplate": "twins/${twin_id}/status",
  • "type": "READ"
}

Response samples

Content type
application/json
{
  • "brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
  • "responseTopicNameTemplate": "twins/${twin_id}/status",
  • "requestTopicNameTemplate": "twins/${twin_id}/status",
  • "id": "5821L",
  • "type": "READ"
}

Delete MQTT Endpoint Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template.

id
required
integer <int64>

The ID of the MQTT Endpoint Template that is being deleted.

Responses

Partially update MQTT Endpoint Template

Performs a partial update on a MQTT Endpoint Template.
The API uses the JSON Merge Patch convention see https://datatracker.ietf.org/doc/html/rfc7386.

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template.

id
required
integer <int64>

The ID of the MQTT Endpoint Template being updated.

Request Body schema: application/json
required

MQTT Endpoint Template object for update. See semantic for JSON Merge Patch https://tools.ietf.org/html/rfc7386

brokerAddressTemplate
string or null [ 1 .. 2000 ] characters ^(mqtt://|mqtts://|tcp://|ssl://).*

Address template of the broker, preferably unencoded. Will be stored exactly as given. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

responseTopicNameTemplate
string or null [ 1 .. 400 ] characters

A template for the topic name of the MqttEndpoint. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

requestTopicNameTemplate
string or null [ 1 .. 400 ] characters

A template for the topic name of the MqttEndpoint. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

type
string or null [ 1 .. 4 ] characters
Enum: "READ" "OPERATIONS"

Responses

Request samples

Content type
application/json
{
  • "brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
  • "responseTopicNameTemplate": "twins/${twin_id}/status",
  • "requestTopicNameTemplate": "twins/${twin_id}/status",
  • "type": "READ"
}

Response samples

Content type
application/json
{
  • "brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
  • "responseTopicNameTemplate": "twins/${twin_id}/status",
  • "requestTopicNameTemplate": "twins/${twin_id}/status",
  • "id": "5821L",
  • "type": "READ"
}

MQTT Endpoint Template

Authorizations:
registry
path Parameters
tenantId
required
string <uuid>

Unique identifier of the owning tenant.

templateId
required
integer <int64>

The ID of the Aspect Template.

id
required
integer <int64>

The ID of the MQTT Endpoint Template being updated.

Request Body schema: application/json
required

MQTT Endpoint Template object which will replace to the registry.

brokerAddressTemplate
required
string (BrokerAddressTemplate) [ 1 .. 2000 ] characters ^(mqtt://|mqtts://|tcp://|ssl://).*

Address template of the broker, preferably unencoded. Will be stored exactly as given. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

responseTopicNameTemplate
required
string (TopicNameTemplate) [ 1 .. 400 ] characters

A template for the topic name of the MqttEndpoint. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

requestTopicNameTemplate
string (TopicNameTemplate) [ 1 .. 400 ] characters

A template for the topic name of the MqttEndpoint. Template parameters are given in the form ${param}. Template parameters are resolved when an aspect is resolved in the context of a Digital Twin. Please see this page for more details about the available placeholders and how they work.

type
required
string (MqttEndpointType) [ 1 .. 4 ] characters
Enum: "READ" "OPERATIONS"

Responses

Request samples

Content type
application/json
{
  • "brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
  • "responseTopicNameTemplate": "twins/${twin_id}/status",
  • "requestTopicNameTemplate": "twins/${twin_id}/status",
  • "type": "READ"
}

Response samples

Content type
application/json
{
  • "brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
  • "responseTopicNameTemplate": "twins/${twin_id}/status",
  • "requestTopicNameTemplate": "twins/${twin_id}/status",
  • "id": "5821L",
  • "type": "READ"
}