---
title: "Update device metadata"
method: PUT
path: "/api/v1/devices/{deviceId}/metadata"
tags: ["Devices"]
---

# Update device metadata

`PUT /api/v1/devices/{deviceId}/metadata`

Device metadata represent configuration of the relationship between the plgd hub and the device. It's not configuration of the device itself. [Twin](https%3A%2F%2Fplgd.dev%2Ffeatures%2Fdevice-shadow%2F) configuration is part of the metadata. By setting this value you control if the shadow for this device is kept up to date or not.

## Path parameters

- `deviceId` string, uuid, required

## Query parameters

- `timeToLive` integer

## Request body

- DeviceMetadata
  - `status` object
    - `value` 'OFFLINE' | 'ONLINE'
    - `validUntil` string, int64 — Unix timestamp in nanoseconds.
    - `connectedAt` string, int64 — Unix timestamp in nanoseconds.
    - `serviceId` string — The service.ID, which identify the device being served, must be set when the status is ONLINE. However, during an OFFLINE event, they will be sed to empty values.
    - `localEndpoints` string[] — The last local endpoints of the device, and it is set when the status is ONLINE.
  - `twinSynchronization` TwinSynchronization
    - `state` 'OUT_OF_SYNC' | 'DISABLED' | 'SYNCING' | 'IN_SYNC' — OUT_OF_SYNC - As soon as it connects after it was offline or when it goes errorless offline or when twin enabled has been changed to true. DISABLED - As soon as twin enabled is set to false. SYNCING - As soon as device connects, successfully signs in and batch observe is called on device from the cloud. IN_SYNC - As soon as current device resources values are received and applied to twin database. Twin was successfully reconciled after device reconnect and is kept up to date using an active subscription to device resource changes.
    - `syncingAt` string, int64
    - `inSyncAt` string, int64
    - `commandMetadata` CommandMetadata
      - `connectionId` string
      - `sequence` string, uint64
  - `twinEnabled` boolean

## Response `200`

Metadata successfully updated.

## Other responses

- `400` — Bad Request
- `401` — Not authorized
- `404` — Entity was not found.

## Changes

> 42 revisions in range; 3 not diffed.

- **2024-02-29** `24b9261b39f3` — 2 info
  - added the new optional request property `status/localEndpoints`
  - added the new optional request property `status/serviceId`
- **2022-11-08** `482579a45b1d` — 1 warning, 2 info
  - removed the request property `shadowSynchronization`
  - added the new optional request property `twinEnabled`
  - added the new optional request property `twinSynchronization`
- **2022-10-17** `1e8fcc1d1354` — 1 info
  - added the new optional request property `status/connectedAt`
- **2022-01-05** `afc9b9af73b5` — 4 info
  - added the optional property `error/details/items/typeUrl` to the response with the `400` status
  - added the optional property `error/details/items/typeUrl` to the response with the `401` status
  - added the optional property `error/details/items/value` to the response with the `400` status
  - added the optional property `error/details/items/value` to the response with the `401` status
- **2021-08-05** `750a4952762c` — 1 info
  - added the new optional `query` request parameter `timeToLive`

[Full history](https://skmtc.dev/plgd-dev/apis/plgd-http-gateway/changes/api/v1/devices/:deviceId/metadata/put.md)

---

[API](https://skmtc.dev/plgd-dev/apis/plgd-http-gateway.md) · [All operations](https://skmtc.dev/plgd-dev/apis/plgd-http-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/plgd-dev/plgd-http-gateway/revisions/bbfd9fa43407/schema)