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:

macma

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
List all paginated
Simple filter
Complex filter

# List all DTs for the tenant

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

Response samples

200
400

Content type

application/json

{"items": [{"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": [{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}
],
"localIdentifiers": [{"id": "5821L",
"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
],
"hash": "string"
}
],
"labels": ["string"
],
"groups": [{"id": "5821L"
}
]
}
],
"nextCursor": "string",
"itemCount": 0
}

Registers a Twin

Authorizations:

macma

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 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
required	Array of objects (LocalIdentifierCreateDto) [ 1 .. 10 ] items unique Local Identifiers of the Twin
labels	Array of strings or null <= 10 items unique Labels of the Twin
groups	Array of integers or null <int64> (EntityId) <= 50 items unique Twin Groups in which the Twin shall be a member.

Responses

Request samples

Payload

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": [{"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
]
}
],
"labels": ["string"
],
"groups": ["5821L"
]
}

Response samples

201
400
422

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": [{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}
],
"localIdentifiers": [{"id": "5821L",
"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
],
"hash": "string"
}
],
"labels": ["string"
],
"groups": [{"id": "5821L"
}
]
}

Gets a Twin

Authorizations:

macma

path Parameters

tenantId required	string <uuid> Unique identifier of the owning tenant.
twinId required	integer <int64> Unique identifier of the Twin.

Responses

Response samples

200

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": [{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}
],
"localIdentifiers": [{"id": "5821L",
"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
],
"hash": "string"
}
],
"labels": ["string"
],
"groups": [{"id": "5821L"
}
]
}

Deletes a Twin

Authorizations:

macma

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:

macma

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	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

Payload

Content type

application/json

{"localIdentifiers": [{"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
]
}
],
"groups": ["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",
"labels": ["string"
],
"listOperator": "replace"
}

Response samples

200
400
422

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": [{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}
],
"localIdentifiers": [{"id": "5821L",
"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
],
"hash": "string"
}
],
"labels": ["string"
],
"groups": [{"id": "5821L"
}
]
}

Local Identifier

Creates a Local Identifier

Authorizations:

macma

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

Payload

Content type

application/json

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

Response samples

201
400
422

Content type

application/json

{"id": "5821L",
"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
],
"hash": "string"
}

Replace a Local Identifier

Authorizations:

macma

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

Payload

Content type

application/json

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

Response samples

200
400
422

Content type

application/json

{"id": "5821L",
"localIdentifierKeyPairs": [{"key": "string",
"value": "string"
}
],
"hash": "string"
}

Deletes a Local Identifier

Authorizations:

macma

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:

macma

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 or null (MqttEndpointCreateDto) unique MQTT endpoint of the Aspect

Responses

Request samples

Payload

Content type

application/json

{"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"type": "READ"
}
]
}

Response samples

201
400
422

Content type

application/json

{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}

Retrieves an Aspect

Authorizations:

macma

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

200

Content type

application/json

{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}

Replace an Aspect

Authorizations:

macma

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 or null (MqttEndpointReplaceDto) unique MQTT endpoint of the Aspect

Responses

Request samples

Payload

Content type

application/json

{"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"type": "READ"
}
]
}

Response samples

200
400
422

Content type

application/json

{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}

Deletes an Aspect

Authorizations:

macma

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:

macma

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

Payload

Content type

application/json

{"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"type": "READ"
}
],
"listOperator": "replace"
}

Response samples

200
400
422

Content type

application/json

{"id": "5821L",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpoints": [{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpoints": [{"brokerAddress": "tcp://broker.mqttdashboard.com:1883",
"responseTopicName": "errors",
"requestTopicName": "errors",
"id": "5821L",
"type": "READ"
}
]
}

Aspect HTTP Endpoint

Creates a HTTP Endpoint

Authorizations:

macma

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.
type required	string (HttpEndpointType) [ 1 .. 20 ] characters Enum: "READ" "FILTER" "OPERATIONS"

Responses

Request samples

Payload

Content type

application/json

{"url": "https://www.bosch-connected-industry.com/en",
"type": "READ"
}

Response samples

201
400
422

Content type

application/json

{"url": "https://www.bosch-connected-industry.com/en",
"id": "5821L",
"method": "POST",
"type": "READ"
}

Deletes a HTTP Endpoint

Authorizations:

macma

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:

macma

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

Payload

Content type

application/json

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

Response samples

201
400
422

Content type

application/json

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

Deletes a MQTT Endpoint

Authorizations:

macma

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:

macma

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

200
400

Content type

application/json

{"items": [{"id": "5821L",
"name": "Drills",
"description": "All drills",
"aspectTemplates": [{"id": "5821L"
}
]
}
],
"nextCursor": "string",
"itemCount": 0
}

Create a new Twin Group

Authorizations:

macma

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 or null <= 4000 characters Detailed description of the Twin Group

Responses

Request samples

Payload

Content type

application/json

{"name": "Drills",
"description": "All drills"
}

Response samples

201
400
422

Content type

application/json

{"id": "5821L",
"name": "Drills",
"description": "All drills",
"aspectTemplates": [{"id": "5821L"
}
]
}

Get Twin Group by ID

Authorizations:

macma

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

200

Content type

application/json

{"id": "5821L",
"name": "Drills",
"description": "All drills",
"aspectTemplates": [{"id": "5821L"
}
]
}

Delete Twin Group

Authorizations:

macma

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:

macma

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

Payload

Content type

application/json

{"name": "Drills",
"description": "All drills",
"listOperator": "replace"
}

Response samples

200
400
422

Content type

application/json

{"id": "5821L",
"name": "Drills",
"description": "All drills",
"aspectTemplates": [{"id": "5821L"
}
]
}

Replace existing Twin Group

Authorizations:

macma

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 or null <= 4000 characters Detailed description of the Twin Group

Responses

Request samples

Payload

Content type

application/json

{"name": "Drills",
"description": "All drills"
}

Response samples

200
400
422

Content type

application/json

{"id": "5821L",
"name": "Drills",
"description": "All drills",
"aspectTemplates": [{"id": "5821L"
}
]
}

Aspect Template

Get Aspect Template by ID

Authorizations:

macma

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

200

Content type

application/json

{"id": "5821L",
"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpointTemplates": [{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpointTemplates": [{"brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
"responseTopicNameTemplate": "twins/${twin_id}/status",
"requestTopicNameTemplate": "twins/${twin_id}/status",
"id": "5821L",
"type": "READ"
}
],
"groups": [{"id": "5821L"
}
]
}

Delete Aspect Template

Authorizations:

macma

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:

macma

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

Payload

Content type

application/json

{"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors"
},
"groups": ["5821L"
],
"listOperator": "replace"
}

Response samples

200
400
422

Content type

application/json

{"id": "5821L",
"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpointTemplates": [{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpointTemplates": [{"brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
"responseTopicNameTemplate": "twins/${twin_id}/status",
"requestTopicNameTemplate": "twins/${twin_id}/status",
"id": "5821L",
"type": "READ"
}
],
"groups": [{"id": "5821L"
}
]
}

Replace existing Aspect Template

Authorizations:

macma

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 or null (MqttEndpointTemplateCreateDto) unique MQTT endpoint templates of the Aspect. Currently ignored for the PUT replacement.
groups	Array of integers or null <int64> (EntityId) <= 50 items unique Twin Groups to which the Aspect Template is assigned.

Responses

Request samples

Payload

Content type

application/json

{"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors"
},
"httpEndpointTemplates": [{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"type": "READ"
}
],
"mqttEndpointTemplates": [{"brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
"responseTopicNameTemplate": "twins/${twin_id}/status",
"requestTopicNameTemplate": "twins/${twin_id}/status",
"type": "READ"
}
],
"groups": ["5821L"
]
}

Response samples

200
400
422

Content type

application/json

{"id": "5821L",
"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpointTemplates": [{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpointTemplates": [{"brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
"responseTopicNameTemplate": "twins/${twin_id}/status",
"requestTopicNameTemplate": "twins/${twin_id}/status",
"id": "5821L",
"type": "READ"
}
],
"groups": [{"id": "5821L"
}
]
}

Lists or queries Aspect Templates with cursor pagination

Authorizations:

macma

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

200
400

Content type

application/json

{"items": [{"id": "5821L",
"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpointTemplates": [{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpointTemplates": [{"brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
"responseTopicNameTemplate": "twins/${twin_id}/status",
"requestTopicNameTemplate": "twins/${twin_id}/status",
"id": "5821L",
"type": "READ"
}
],
"groups": [{"id": "5821L"
}
]
}
],
"nextCursor": "string",
"itemCount": 0
}

Create a new Aspect Template

Authorizations:

macma

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 or null (MqttEndpointTemplateCreateDto) unique MQTT endpoint templates of the Aspect. Currently ignored for the PUT replacement.
groups	Array of integers or null <int64> (EntityId) <= 50 items unique Twin Groups to which the Aspect Template is assigned.

Responses

Request samples

Payload

Content type

application/json

{"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors"
},
"httpEndpointTemplates": [{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"type": "READ"
}
],
"mqttEndpointTemplates": [{"brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
"responseTopicNameTemplate": "twins/${twin_id}/status",
"requestTopicNameTemplate": "twins/${twin_id}/status",
"type": "READ"
}
],
"groups": ["5821L"
]
}

Response samples

201
400
422

Content type

application/json

{"id": "5821L",
"name": "Movement aspect template",
"modelReference": {"urn": "urn:samm:com.bosch.nexeed.digitaltwin:1.0.0#Errors",
"aspectName": "Errors",
"aspectVersion": "1.0.0"
},
"httpEndpointTemplates": [{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}
],
"mqttEndpointTemplates": [{"brokerAddressTemplate": "tcp://broker.${twin_id}.mqttdashboard.com:1883",
"responseTopicNameTemplate": "twins/${twin_id}/status",
"requestTopicNameTemplate": "twins/${twin_id}/status",
"id": "5821L",
"type": "READ"
}
],
"groups": [{"id": "5821L"
}
]
}

HTTP Endpoint Template

Create a new HTTP Endpoint Template

Authorizations:

macma

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.
type required	string (HttpEndpointType) [ 1 .. 20 ] characters Enum: "READ" "FILTER" "OPERATIONS"

Responses

Request samples

Payload

Content type

application/json

{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"type": "READ"
}

Response samples

201
400
422

Content type

application/json

{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}

Delete HTTP Endpoint Template

Authorizations:

macma

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:

macma

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.
type	string or null [ 1 .. 20 ] characters Enum: "READ" "FILTER" "OPERATIONS"

Responses

Request samples

Payload

Content type

application/json

{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"type": "READ"
}

Response samples

200
400
422

Content type

application/json

{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}

HTTP Endpoint Template

Authorizations:

macma

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.
type required	string (HttpEndpointType) [ 1 .. 20 ] characters Enum: "READ" "FILTER" "OPERATIONS"

Responses

Request samples

Payload

Content type

application/json

{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"type": "READ"
}

Response samples

200
400
422

Content type

application/json

{"urlTemplate": "https://www.bosch-connected-industry.com/twins/${twin_id}",
"id": "5821L",
"method": "POST",
"type": "READ"
}

MQTT Endpoint Template

Create a new MQTT Endpoint Template

Authorizations:

macma

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.
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.
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.
type required	string (MqttEndpointType) [ 1 .. 4 ] characters Enum: "READ" "OPERATIONS"

Responses

Request samples

Payload

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

201
400
422

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:

macma

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:

macma

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.
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.
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.
type	string or null [ 1 .. 4 ] characters Enum: "READ" "OPERATIONS"

Responses

Request samples

Payload

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

200
400
422

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:

macma

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.
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.
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.
type required	string (MqttEndpointType) [ 1 .. 4 ] characters Enum: "READ" "OPERATIONS"

Responses

Request samples

Payload

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

200
400
422

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"
}

Digital Twin Registry API (v2)

Authentication

Digital Twin

Lists or queries Twins with cursor pagination

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Registers a Twin

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Gets a Twin

Authorizations:

path Parameters

Responses

Response samples

Deletes a Twin

Authorizations:

path Parameters

Responses

Merge a Twin

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Local Identifier

Creates a Local Identifier

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Replace a Local Identifier

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Deletes a Local Identifier

Authorizations:

path Parameters

Responses

Aspect

Creates an Aspect

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Retrieves an Aspect

Authorizations:

path Parameters

Responses

Response samples

Replace an Aspect

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Deletes an Aspect

Authorizations:

path Parameters

Responses

Merge an Aspect

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

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