---
title: "Rename a device, change its platform, or report its app build"
method: PATCH
path: "/api/v1/devices/{id}"
tags: ["Devices"]
---

# Rename a device, change its platform, or report its app build

`PATCH /api/v1/devices/{id}`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/devices/{id}`
- Auth: API key in header `api-key`

Owner or root: any field. The device's own api-key (its own id only): `app_version` and `app_commit` only, so the computer can report which Salt Device build it runs; `name` or `platform` from a device key is a 403. Send only the fields to change; a blank `app_version` or `app_commit` clears it. A change is announced on the `devices` live topic to the owner and root.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string
  - `platform` 'macos' | 'windows'
  - `app_version` string: The Salt Device version this computer runs. Blank clears.
  - `app_commit` string: The git commit of that build (7-40 hex). Blank clears.

## Response `200`

OK.

- object
  - `id` string
  - `name` string
  - `platform` 'macos' | 'windows'
  - `username` string
  - `public_fingerprint` string
  - `owner_id` string
  - `created_at` string, date-time
  - `socket_seen_at` string, date-time, nullable
  - `app_version` string, nullable: The Salt Device version this computer runs (e.g. `0.2.2`), as the device reported it. Null until it has.
  - `app_commit` string, nullable: The git commit that build was made from (7-40 lowercase hex). Null until reported.
  - `live_session` boolean
  - `public_key` string: The computer's armored public key: what a person encrypts a live-view offer to, and verifies its answer against.
  - `fingerprint` string: The same fingerprint as `public_fingerprint`.
  - `can_watch` boolean: Salt Device 0.4 or newer on a Mac: this computer can show its screen live.
  - `watching` object[], nullable: `GET /devices` only, for the device's owner and root: who is watching its screen now. Null for anyone else.
    - `viewer_id` string
    - `call_id` string
  - `offline_since` string, date-time, nullable: `GET /devices` only. When the computer is not online (no live session holds it and its socket was not seen in the last 5 minutes): the time it was last seen. Null when online or never seen.
  - `lost_contact` object, nullable: `GET /devices` only, for the device's owner and root. Set when the most recent session that worked on this computer ended `lost_contact` (it stopped answering for 15 seconds) and the computer has not been seen alive since; null otherwise.
    - `agent_id` string
    - `agent_name` string
    - `ended_at` string, date-time
  - `api_key` string: Returned once, on create only.

## Other responses

- `401`: Missing or invalid credentials.
- `403`: A device key sent name or platform.
- `404`: Unknown, not yours, or the feature is off.
- `422`: Bad name, platform, app_version or app_commit.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)