Rename a device

Part of Devices, 10 operations. The overview covers keys, scopes and errors.

PATCH /v1/devices/{device_id}

Set the device label. The label survives later activity from the device.

A caller key holding devices:write (Authorization: Bearer sbc_… or x-api-key: sbc_…), or a signed-in session.

Operation id updateDevice in Devices.

Path parameters

device_id string required
The device id (a Device id).

Request body

application/json, required.

label string required
The new label, 1-64 printable characters (trimmed).

Response 200

The renamed device.

application/json: Device.

id string required
object string required
One of device.
kind string required
label string required
fingerprint string required
created_at string required
last_seen_at string | null required
online boolean required
capabilities object
5 fields
- tools_count integer required
- hub_port integer
- helper_version string
- held_vendors array of string required
- held_models array of string required
agent AgentDeviceFacet
Present only on a Device of kind agent_computer.
6 fields
- agent_vendor string required
  The agent VM vendor, as it declared itself at link time. generic is any other agent. One of grok-bot, muse, dots, manus, cursor-cloud, devin, replit, genspark, kimi, generic.
- tier string required
  link: terminal and relay only. data: link plus the synced data the linking app granted. One of link, data.
- state string required
  online: polling now. asleep: suspended by its vendor (jobs wait queued_asleep). offline: not seen recently. One of online, asleep, offline.
- expires_at string required
  The next lifecycle deadline (ISO 8601), the one expiry_kind names. Warned 3 days ahead.
- expiry_kind string required
  data_idle: 14 days idle drops the data tier to link. reconfirm: the 90-day re-confirm is due (missed: link tier). link_idle: 30 days idle unlinks it. One of data_idle, reconfirm, link_idle.
- reconfirm_due_at string | null required
  When the data tier must be re-confirmed (POST /me/devices/{device_id}/agent-reconfirm); null at the link tier.
key string
Whether this device holds the account's current end-to-end encryption key, from its own last report. linked: it holds the current key. not_linked: it holds none (it can still add logins, which reach the other devices). out_of_date: it holds an older or a different key. unknown: it has not reported, or the account has no key yet. Absent on a device that holds no key (an agent computer, an API key, an MCP connector, the cloud computer, a web browser: browsers never hold the key). A desktop app reports through its Helper (custody_via). One of linked, not_linked, out_of_date, unknown.
custody_via string
The id of the device whose key this one uses (a desktop app names its Helper); key is that device's state. Absent when the device holds its own.
created_via string
Present only on a Device of kind agent_computer. app_link: linked through the app-minted link, so the vendor was recorded by the app and may be shown as verified. device_code: the agent claimed its own vendor at a device-code approval, so show it as unverified. A missing value is device_code. One of app_link, device_code.

Errors

Status	Code	What to change
400	`invalid_request`	A parameter or body field is invalid; `param` names it and `issues` lists every problem.
401	`unauthorized`	Send a live caller key or session as `Authorization: Bearer …` or `x-api-key`. No key yet: create one at /account/api, or sign a user in at /auth.md.
403	`insufficient_scope`	The key lacks the scope in `required_scopes`; mint a key that holds it.
404	`not_found`	No such resource on this account; check the id.
429	`rate_limited`	Over the per-key request bucket; retry after `x-ratelimit-reset`.

view .md openapi

Request

curl

curl -sS -X PATCH "https://superbot.gg/v1/devices/$DEVICE_ID" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"label":"Studio Mac"}'

JavaScript

const deviceId = 'DEVICE_ID';
const res = await fetch(`https://superbot.gg/v1/devices/${deviceId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({"label":"Studio Mac"}),
});
console.log(res.status, await res.json());

Python

import os
import requests

device_id = "DEVICE_ID"
res = requests.request(
    "PATCH",
    f"https://superbot.gg/v1/devices/{device_id}",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
        "content-type": "application/json",
    },
    json={"label":"Studio Mac"},
)
print(res.status_code, res.json())

Response

200 The renamed device.

{
  "id": "your-id",
  "object": "device",
  "kind": "your-kind",
  "label": "your-label",
  "fingerprint": "your-fingerprint",
  "created_at": "your-created-at",
  "last_seen_at": "your-last-seen-at",
  "online": true,
  "capabilities": {
    "tools_count": 0,
    "hub_port": 0,
    "helper_version": "your-helper-version",
    "held_vendors": [
      "your-held-vendors"
    ],
    "held_models": [
      "your-held-models"
    ]
  },
  "agent": {
    "agent_vendor": "grok-bot",
    "tier": "link",
    "state": "online",
    "expires_at": "your-expires-at",
    "expiry_kind": "data_idle",
    "reconfirm_due_at": "your-reconfirm-due-at"
  },
  "key": "linked",
  "custody_via": "your-custody-via",
  "created_via": "app_link"
}

400 The request is malformed or a parameter is invalid; `param` names the field.

{
  "error": "invalid_request",
  "message": "A parameter or body field is invalid; param names it and issues lists every problem.",
  "doc_url": "https://superbot.gg/developers#errors-invalid_request",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

401 The bearer is missing, malformed or unknown.

{
  "error": "unauthorized",
  "message": "Send a live caller key or session as Authorization: Bearer … or x-api-key. No key yet: create one at /account/api, or sign a user in at /auth.md.",
  "doc_url": "https://superbot.gg/developers#errors-unauthorized",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

403 The key lacks a scope (insufficient_scope), is revoked, or may not call this route.

{
  "error": "insufficient_scope",
  "message": "The key lacks the scope in required_scopes; mint a key that holds it.",
  "doc_url": "https://superbot.gg/developers#errors-insufficient_scope",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

404 No such resource on this account.

{
  "error": "not_found",
  "message": "No such resource on this account; check the id.",
  "doc_url": "https://superbot.gg/developers#errors-not_found",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}

429 Over the per-key request bucket; retry after x-ratelimit-reset.

{
  "error": "rate_limited",
  "message": "Over the per-key request bucket; retry after x-ratelimit-reset.",
  "doc_url": "https://superbot.gg/developers#errors-rate_limited",
  "request_id": "req_5f1c0a9e2b7d4c3a1e0f9b8d"
}