---
title: "Update Robot"
method: PATCH
path: "/robots/{robot_id}"
tags: ["robots"]
---

# Update Robot

`PATCH /robots/{robot_id}`

## Request

- Base URL: `https://api.os3robotics.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.os3robotics.com/robots/{robot_id}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Owners and admins: the embodiment and runtime identity registered for this robot.
A revoked robot is 409. Name, workspace and serial stay as they were at registration.
An endpoint serves the robot only when it expects the identity registered here. An identity
that the release of an unfinished controller rollout still going to the robot would not have
been rolled out to (an embodiment it does not drive, a controller API it does not meet) is
409, naming the rollout and why: let it finish, or roll it back, first.

## Path parameters

- `robot_id` string, uuid, required

## Request body

- RobotIdentity: What a robot is: given by POST /robots or by the robot itself at POST /provision, and changed by an owner or admin with PATCH /robots/{robot_id}.
  - `action_space_id` string
  - `wire_contract_version` string
  - `camera_shapes` object, required
  - `controller_api_version` string, required
  - `embodiment` string, required

## Response `200`

Successful Response

- Robot: A robot row as the API shows it: never the credential, its prefix or its hash.
  - `id` string, uuid, required
  - `tenant_id` string, uuid, required
  - `workspace_id` string, uuid, required
  - `name` string, required
  - `embodiment` string, required
  - `action_space_id` string, required
  - `wire_contract_version` string, required
  - `camera_shapes` object, required
  - `controller_api_version` string, required
  - `calibration_sha256` string, nullable, required
  - `serial` string, nullable, required
  - `status` 'registered' | 'connected' | 'revoked', required
  - `credential_issued_at` string, date-time, required
  - `created_at` string, date-time, required
  - `last_seen_at` string, date-time, nullable, required
  - `revoked_at` string, date-time, nullable, required
  - `deleted_at` string, date-time, nullable
  - `specs` RobotSpecs, required: What the robot agent reports on its heartbeat (the registered identity, embodiment, action_space_id and the policy's camera_shapes, are the Robot's own fields).
    - `dof` integer, nullable
    - `cameras` object
    - `agent_version` string, nullable
    - `firmware_version` string, nullable
    - `rig` string, nullable
  - `live` RobotLive, required
    - `online` boolean, required
    - `endpoint_id` string, uuid, nullable, required
    - `latency_ms` number, nullable, required
    - `voice` VoiceHealth: The robot's voice fallback state at its heartbeat: the current rung of its degradation ladder, backend names and reasons, never audio or text.
      - `rung` 'full' | 'cascade' | 'local_only' | 'voice_paused' | 'audio_lost', required
      - `backend` string, nullable
      - `unhealthy_backends` string[]
      - `harness_dead` boolean
      - `reason` string, nullable
  - `connection` RobotConnection, required: How the robot reaches its endpoints: `direct_tls`, or `tailnet` once it joined OS3's tailnet (POST /robots/tailnet: its node's name and its tenant's robot tag).
    - `mode` 'direct_tls' | 'tailnet', required
    - `tailnet_node` string, nullable, required
    - `tailnet_ip` string, nullable, required
    - `tailnet_tag` string, nullable, required
  - `capabilities` RobotCapabilities, required
    - `teleop` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/os3robotics/apis/os3-api.md) - [All operations](https://skmtc.dev/os3robotics/apis/os3-api/llms.txt) - [OpenAPI document](https://skmtc.dev/os3robotics/apis/os3-api/revisions/af32cd4f14bb?raw)