Update Asset Data with Tandem Data API

When working with a digital twin, you need to be able to read and write asset data via the API. In the previous article, we learned how to read data using the Tandem Data API. This article explains how to update asset information using the API, with practical tips and examples.

Write element data

The POST mutate endpoint updates facility elements by writing data to the backend database. It supports updating a single asset as well as multiple assets in batch mode.
Facilities typically include multiple models, and the mutate endpoint operates per model.

Request

The mutate endpoint is a POST request that accepts a JSON payload:

keys — the IDs of the elements to update. Provide an array of element IDs, for example:

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg"
  ],
  …
}

muts — specifies the changes. Each change is an array of four items: change type, property family ID, property column ID, and the new value. For example, here we set the custom property (z:1Bw) to Test.

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg"
  ],
  "muts": [
    [ "i", "z", "1Bw", "Test"]
  ],
  …
}

The following types of changes are supported:

• i (insert) - sets the value of property to a new value.
• c (insert if different) – sets a new value only if there is a difference compared to the current value. This can be useful to keep the history of changes clean.
• a (delete) – sets the value to empty.

The property IDs can be obtained from the model schema. The schema can also be used to determine the value type (for example, string, number, date). You can also use predefined constants to specify families and properties:

export const ColumnFamilies = {
    DtProperties:   'z',
    LMV:            '0',
    Source:         'r',
    …
};

export const ColumnNames = {
    BoundingBox:        '0',
    CategoryId:         'c',
    Classification:     'v',
    OClassification:    '!v',
    ElementFlags:       'a',
    Elevation:          'el',
    FamilyType:         't',
    Level:              'l',
    OLevel:             '!l',
    Name:               'n',
    OName:              '!n',
    …
};

You can specify multiple changes in a single call—for example, change the classification and set a custom parameter value:

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg",
    "H_pwafaOSk2EClLjcqgo1ABb2Dg"
  ],
  "muts": [
    ["i", "n", "!v", "Interior Doors"],
    ["i", "z", "1Bw", "Test"]
  ]
  …
}

In this case, the number of items in the keys array must match the number of items in the muts array—two items. To apply multiple changes to the same element, repeat the same key accordingly.

desc – is used to provide a description of the changes. This can be used to find the change in history.

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg",
    "H_pwafaOSk2EClLjcqgo1ABb2Dg"
  ],
  "muts": [
    ["i", "n", "!v", "B2030"],
    ["i", "z", "1Bw", "Test"]
  ],
  "desc": "Update parameters"
}

correlationID – optional unique ID (for example, a GUID) used to correlate changes across multiple models.

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg",
    "H_pwafaOSk2EClLjcqgo1ABb2Dg"
  ],
  "muts": [
    ["i", "n", "!v", "B2030"],
    ["i", "z", "1Bw", "Test"]
  ],
  "desc": "Update parameters",
  "correlationID": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Response

The response then contains a timestamp indicating when the change was applied:

{
  "timestamp": 1755590812404
}

Examples

Here is a .http file that demonstrates the exact requests. Use a REST client to view and interact with the .http file (for example, install the httpYac extension inside VSCode):

### Global variables
@baseUrl=https://developer.api.autodesk.com/tandem/v1
@modelId=urn:adsk.dtm:CPLXRtNCTlOSKVGQZVhLJw
@authToken=eyJ....EpHg


### Create mutate request
# Response Schema:
# {
#   "timestamp": "number"
# }
# @name updateName
POST {{baseUrl}}/modeldata/{{modelId}}/mutate
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{authToken}}

{
  "keys": [
    "AAAAALZJKyIr9kzapDIlS9nXh5wAJUN5"
  ],
  "muts": [
    [
      "i",
      "n",
      "!n",
      "Triangular Pump"
    ]
  ],
  "desc": "Update name"
}
###


# @name updateNameAndClassification
POST {{baseUrl}}/modeldata/{{modelId}}/mutate
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{authToken}}

{
  "keys": [
    "AAAAALZJKyIr9kzapDIlS9nXh5wAJUN5",
    "AAAAALZJKyIr9kzapDIlS9nXh5wAJUN5"
  ],
  "muts": [
    [
      "i",
      "n",
      "!n",
      "Circulator Pump"
    ],
    [
      "i",
      "n",
      "!v",
      "3d"
    ]
  ],
  "desc": "Update name and classification"
}

# @name updateClassificationMultipleElements
POST {{baseUrl}}/modeldata/{{modelId}}/mutate
Content-Type: application/json
Accept: application/json
Authorization: Bearer {{authToken}}

{
  "keys": [
    "AAAAALZJKyIr9kzapDIlS9nXh5wAJUN5",
    "AAAAANAVpEgPG0HessRFQqGX-cQAJPjW"
  ],
  "muts": [
    [
      "i",
      "n",
      "!v",
      "3d"
    ],
    [
      "i",
      "n",
      "!v",
      "3d"
    ]
  ],
  "desc": "Update classification"
}

This section includes input payload examples for common scenarios.

Update name of element:

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg"
  ],
  "muts": [
    ["i", "n", "!n", "Circulator Pump"]
  ],
  "desc": "Update name"
}

Update name and classification of an element. Note that the classification value depends on the applied facility template:

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg",
    "H_pwafaOSk2EClLjcqgo1ABb2Dg"
  ],
  "muts": [
    ["i", "n", "!n", "Circulator Pump"],
    ["i", "n", "!v", "B2030"]
  ],
  "desc": "Update name+classification"
}

Update classification of multiple elements.

{
  "keys": [
    "H_pwafaOSk2EClLjcqgo1ABb2Dg",
    "H_pwafaOSk2EClLjcqgo3EDcA6a"
  ],
  "muts": [
    ["i", "n", "!v", "B2030"],
    ["i", "n", "!v", "B2030"]
  ],
  "desc": "Update classification"
}

Recommendations

• Use a schema to find out the type of a property.
• Use an RFC 3339–formatted string when the property type is a date.
• Use bulk updates when possible. This reduces load on the server.
• For bulk updates across multiple models, include correlationID in the payload to maintain a consistent view in the facility history.
• When updating multiple elements, the payload size is limited to 10 MB.
• Consider using streams for frequent data changes.

Wrap Up

In this article, you learned how to use the API to update asset data. For additional details, visit the official documentation. You can find the code samples on GitHub (JavaScript and Python).
Feel free to contact us with any questions or if you need help with the Tandem API.  You can also submit your questions directly to the Support team via your ADN portal (submit a support ticket) via publicly via Stack Overflow and remember to mark them with the autodesk-tandem tag.