List devices

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

GET /v1/devices

The devices paired to this account, oldest first, paged by device id. online filters on presence (seen within the last two minutes). Revoked devices are not listed.

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

Operation id listDevices in Devices.

Query parameters

limit integer optional
Items per page, 1-100.
after_id string optional
Return the page after this resource id (the previous page’s last_id).
before_id string optional
Return the page before this resource id (the next page’s first_id).
online string optional
Only devices that are (true) or are not (false) online now. One of true, false.

Response 200

A page of devices.

application/json: DeviceList.

object string required
One of list.
data array of Device required
13 fields
- 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.
has_more boolean required
first_id string | null required
Id of the first item on this page; pass as before_id for the previous page.
last_id string | null required
Id of the last item on this page; pass as after_id for the next page.

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.
429	`rate_limited`	Over the per-key request bucket; retry after `x-ratelimit-reset`.

view .md openapi

Request

curl

curl -sS -X GET "https://superbot.gg/v1/devices" \
  -H "Authorization: Bearer $SUPERBOT_API_KEY"

JavaScript

const res = await fetch(`https://superbot.gg/v1/devices`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SUPERBOT_API_KEY}`,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.request(
    "GET",
    "https://superbot.gg/v1/devices",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERBOT_API_KEY']}",
    },
)
print(res.status_code, res.json())

Response

200 A page of devices.

{
  "object": "list",
  "data": [
    {
      "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": [],
        "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"
    }
  ],
  "has_more": true,
  "first_id": "your-first-id",
  "last_id": "your-last-id"
}

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"
}

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"
}