---
title: "Load entities version (loadEntitiesVersion)"
method: POST
path: "/api/entities/vc/entity"
tags: ["entities-version-control-controller"]
---

# Load entities version (loadEntitiesVersion)

`POST /api/entities/vc/entity`

Loads specific version of remote entities (or single entity) by request. Supported entity types: CUSTOMER, ASSET, RULE_CHAIN, DASHBOARD, DEVICE_PROFILE, DEVICE, ENTITY_VIEW, WIDGETS_BUNDLE.

There are multiple types of request. Each of them requires branch name (`branch`) and version id (`versionId`). Request of type `SINGLE_ENTITY` is needed to restore a concrete version of a specific entity. It contains id of a remote entity (`externalEntityId`) and additional configuration (`config`):
- `loadRelations` - to update relations list (in case `saveRelations` option was enabled during version creation);
- `loadAttributes` - to load entity attributes (if `saveAttributes` config option was enabled);
- `loadCredentials` - to update device credentials (if `saveCredentials` option was enabled during version creation).

An example of such request:
```json
{
  "type": "SINGLE_ENTITY",
  
  "branch": "dev",
  "versionId": "b3c28d722d328324c7c15b0b30047b0c40011cf7",
  
  "externalEntityId": {
    "entityType": "DEVICE",
    "id": "b7944123-d4f4-11ec-847b-0f432358ab48"
  },
  "config": {
    "loadRelations": false,
    "loadAttributes": true,
    "loadCredentials": true
  }
}
```

Another request type (`ENTITY_TYPE`) is needed to load specific version of the whole entity types. It contains a structure with entity types to load and configs for each entity type (`entityTypes`). For each specified entity type, the method will load all remote entities of this type that are present at the version. A config for each entity type contains the same options as in `SINGLE_ENTITY` request type, and additionally contains following options:
- `removeOtherEntities` - to remove local entities that are not present on the remote - basically to    overwrite local entity type with the remote one;
- `findExistingEntityByName` - when you are loading some remote entities that are not yet present at this tenant,    try to find existing entity by name and update it rather than create new.

Here is an example of the request to completely restore version of the whole device entity type:
```json
{
  "type": "ENTITY_TYPE",

  "branch": "dev",
  "versionId": "b3c28d722d328324c7c15b0b30047b0c40011cf7",

  "entityTypes": {
    "DEVICE": {
      "removeOtherEntities": true,
      "findExistingEntityByName": false,
      "loadRelations": true,
      "loadAttributes": true,
      "loadCredentials": true
    }
  }
}
```

The response will contain generated request UUID that is to be used to check the status of operation via `getVersionLoadRequestStatus`.

Available for users with 'TENANT_ADMIN' authority.

## Request body

- union
  - EntityTypeVersionLoadRequest
    - `versionId` string
    - `type` 'SINGLE_ENTITY' | 'ENTITY_TYPE'
    - `entityTypes` object
    - `rollbackOnError` boolean
  - SingleEntityVersionLoadRequest
    - `versionId` string
    - `type` 'SINGLE_ENTITY' | 'ENTITY_TYPE'
    - `externalEntityId` EntityId
      - `id` string, uuid, required — ID of the entity, time-based UUID v1
      - `entityType` 'TENANT' | 'CUSTOMER' | 'USER' | 'DASHBOARD' | 'ASSET' | 'DEVICE' | 'ALARM' | 'RULE_CHAIN' | 'RULE_NODE' | 'ENTITY_VIEW' | 'WIDGETS_BUNDLE' | 'WIDGET_TYPE' | 'TENANT_PROFILE' | 'DEVICE_PROFILE' | 'ASSET_PROFILE' | 'API_USAGE_STATE' | 'TB_RESOURCE' | 'OTA_PACKAGE' | 'EDGE' | 'RPC' | 'QUEUE' | 'NOTIFICATION_TARGET' | 'NOTIFICATION_TEMPLATE' | 'NOTIFICATION_REQUEST' | 'NOTIFICATION' | 'NOTIFICATION_RULE' | 'QUEUE_STATS' | 'OAUTH2_CLIENT' | 'DOMAIN' | 'MOBILE_APP' | 'MOBILE_APP_BUNDLE' | 'CALCULATED_FIELD' | 'JOB' | 'ADMIN_SETTINGS' | 'AI_MODEL' | 'API_KEY', required
    - `config` VersionLoadConfig
      - `loadRelations` boolean
      - `loadAttributes` boolean
      - `loadCredentials` boolean
      - `loadCalculatedFields` boolean

## Response `200`

OK

- string, uuid

---

[API](https://skmtc.net/thingsboard/apis/thingsboard-rest-api.md) · [All operations](https://skmtc.net/thingsboard/apis/thingsboard-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/thingsboard/thingsboard-rest-api/revisions/40169ccdec5c/schema)