Sensor API Reference

The /v1/sensors/* endpoints are the device registry for synapse — register, list, inspect, disable, rotate, and revoke the devices that publish telemetry to your Cells. Synapse reads this registry to authenticate each MQTT connection.

Base URL: https://api.tissue.systems

Authentication: Authorization: Bearer <token>, where <token> is a CLI JWT or a tok_ API token. Each endpoint lists the scope it requires.

The same operations are available through the ribo sensor CLI and the MCP tools (sensor_list_devices, sensor_get_device, sensor_register_device, sensor_set_device_enabled, sensor_rotate_device_token, sensor_delete_device).

Register a device

POST /v1/sensors/{cell}/devices — scope cells:write

Registers a new device under the Cell and returns its credentials. The token is returned once and only stored as a SHA-256 hash.

curl -X POST https://api.tissue.systems/v1/sensors/my-cell/devices \
  -H "Authorization: Bearer $TISSUE_TOKEN"

{
  "device_id": "dev_a1b2c3d4",
  "token": "key_0f1e2d3c...",
  "account_id": "acct_9c3f21ab",
  "cell": "my-cell",
  "cell_address": "9c3f21abx7k2p",
  "topic_prefix": "tissue/acct_9c3f21ab/dev_a1b2c3d4/",
  "note": "Save the token now — it is not shown again."
}

List devices for a Cell

GET /v1/sensors/{cell}/devices — scope cells:read

Lists the devices registered to one Cell.

curl https://api.tissue.systems/v1/sensors/my-cell/devices \
  -H "Authorization: Bearer $TISSUE_TOKEN"

{
  "cell": "my-cell",
  "devices": [
    {
      "device_id": "dev_a1b2c3d4",
      "auth_type": "token",
      "enabled": 1,
      "created_at": 1751328000
    }
  ]
}

List all devices in the account

GET /v1/sensors/devices — scope cells:read

Lists every device provisioned under the account, across all Cells. Each device is annotated with its owning cell name (null if the Cell no longer exists).

curl https://api.tissue.systems/v1/sensors/devices \
  -H "Authorization: Bearer $TISSUE_TOKEN"

{
  "account_id": "acct_9c3f21ab",
  "count": 2,
  "devices": [
    {
      "device_id": "dev_a1b2c3d4",
      "cell_address": "9c3f21abx7k2p",
      "auth_type": "token",
      "enabled": 1,
      "home_region": null,
      "created_at": 1751328000,
      "cell": "my-cell"
    }
  ]
}

Get a device

GET /v1/sensors/{cell}/devices/{device_id} — scope cells:read

Fetches a single device's registry record. The token is never returned — only its hash is stored.

curl https://api.tissue.systems/v1/sensors/my-cell/devices/dev_a1b2c3d4 \
  -H "Authorization: Bearer $TISSUE_TOKEN"

{
  "device_id": "dev_a1b2c3d4",
  "cell_address": "9c3f21abx7k2p",
  "auth_type": "token",
  "enabled": 1,
  "home_region": null,
  "created_at": 1751328000,
  "topic_prefix": "tissue/acct_9c3f21ab/dev_a1b2c3d4/",
  "cell": "my-cell"
}

Enable or disable a device

PATCH /v1/sensors/{cell}/devices/{device_id} — scope cells:write

Toggles the device's enabled flag without deleting it. A disabled device is refused at MQTT CONNECT by synapse; its identity and history are preserved.

curl -X PATCH https://api.tissue.systems/v1/sensors/my-cell/devices/dev_a1b2c3d4 \
  -H "Authorization: Bearer $TISSUE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

{
  "device_id": "dev_a1b2c3d4",
  "cell": "my-cell",
  "enabled": false
}

Rotate a device token

POST /v1/sensors/{cell}/devices/{device_id}/rotate — scope cells:write

Issues a new token for the device, keeping its device_id stable. The old token is invalidated immediately. The new token is returned once.

curl -X POST https://api.tissue.systems/v1/sensors/my-cell/devices/dev_a1b2c3d4/rotate \
  -H "Authorization: Bearer $TISSUE_TOKEN"

{
  "device_id": "dev_a1b2c3d4",
  "token": "key_aa11bb22...",
  "account_id": "acct_9c3f21ab",
  "cell": "my-cell",
  "topic_prefix": "tissue/acct_9c3f21ab/dev_a1b2c3d4/",
  "note": "Save the token now — it is not shown again. The previous token no longer works."
}

Delete a device

DELETE /v1/sensors/{cell}/devices/{device_id} — scope cells:delete

Revokes a device. Its credentials stop working immediately and its registry row is removed. Returns 204 No Content.

curl -X DELETE https://api.tissue.systems/v1/sensors/my-cell/devices/dev_a1b2c3d4 \
  -H "Authorization: Bearer $TISSUE_TOKEN"