Appearance
Fleet overview #
Fleet overview endpoints expose device inventory and state for OEM/developer portal integrations. All requests require Authorization: ApiKey <key>.
Base path: /api/developer/
List devices #
GET /api/developer/devices/List devices accessible via device-class ownership.
bash
curl -s \
-H "Authorization: ApiKey $ORG_API_KEY" \
"https://gateway.dataplicity.com/api/developer/devices/"Returns an array of devices visible through Device Class ownership, rather than the count/results envelope used by organisation inventory.
Use limit (maximum 500) and the opaque X-Next-Cursor response header to fetch subsequent pages with cursor. Stop when X-Has-More is 0. For large fleets, use include_counts=0 to omit exact totals; X-Fleet-Has-Devices still distinguishes an empty fleet from a filter with no matches. Use lite=true for a smaller representation.
X-Total-Count is the filtered count; X-Fleet-Total-Count is the accessible count before filters. Both are omitted with include_counts=0.
Get device details #
GET /api/developer/devices/{device_hash}/Returns high-level details for a single device.
bash
curl -s \
-H "Authorization: ApiKey $ORG_API_KEY" \
"https://gateway.dataplicity.com/api/developer/devices/$DEVICE_HASH/"Update device details #
PATCH /api/developer/devices/{device_hash}/Developer-safe partial update. Allowed fields:
| Field | Maps to | Description |
|---|---|---|
name | vendor_name | Display name |
description | vendor_description | Device description |
wormhole_enabled | - | Enable/disable Wormhole |
wormhole_override | - | Wormhole configuration override |
application_location / assigned_location | Device metadata | Validated location object; use null to clear |
bash
curl -s -X PATCH \
-H "Authorization: ApiKey $ORG_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "acme-gateway-042", "description": "Manchester warehouse"}' \
"https://gateway.dataplicity.com/api/developer/devices/$DEVICE_HASH/"Delete device #
DELETE /api/developer/devices/{device_hash}/Remove a device from the developer device management surface. Returns 204 No Content on success.
Fleet map #
GET /api/developer/devices/fleet-map/Return map markers for devices with a known last-seen geo location. Use for fleet map visualisations in your product.
Status refresh #
GET /api/developer/devices/status-refresh/
POST /api/developer/devices/status-refresh/Lightweight online-status refresh without refetching the full device list payload.
Both methods require 1 to 500 device hashes. GET uses repeated hash_id query parameters. POST uses a JSON object:
json
{"hash_ids": ["device-hash-one", "device-hash-two"]}The response is {"devices": [...], "count": 2}. An empty request returns 400; this operation does not refresh the entire fleet implicitly.
Use this to keep online/offline indicators current in dashboards that poll frequently.
Logging #
GET /api/developer/logging/
GET /api/developer/logging/{log_id}/Developer API alias for organisation logs.
- List -
GET /api/developer/logging/ - Get entry -
GET /api/developer/logging/{log_id}/
For organisation-scoped log access, see Organisation operations - Logs.
Wormhole summaries #
GET /api/developer/devices/wormhole-summaries/
GET /api/developer/devices/{device_hash}/wormhole/status/Read wormhole enablement and health across the fleet, or for a single device. Requires developer:devices:read (or mcp:read).
Device timeline #
GET /api/developer/devices/{device_hash}/timeline/Returns results, count, available types, and attachment_limits. Requires developer:devices:read and an entitled plan. Filter with source=operator|system, types, q, and limit (maximum 500).
Read photo content using the attachment URL returned by the API, with the same key and device scope. Timeline comment creation requires a signed-in human author; organisation keys cannot create comments.
Fleet jobs #
GET /api/developer/fleet-jobs/
GET /api/developer/fleet-jobs/{job_id}/
POST /api/developer/fleet-jobs/{job_id}/cancel/List, inspect, and cancel fleet jobs over Gateway. Prefer fleet_jobs:read / fleet_jobs:write (or developer:devices:* / mcp:*). Creating jobs currently requires a signed-in user with device-write permission. It is not part of the organisation API-key contract. Hosted MCP can list, inspect, and cancel.
Endpoint and heartbeat monitors #
GET /api/developer/endpoint-monitors/
GET /api/developer/heartbeat-monitors/List and manage HTTP endpoint monitors and heartbeat monitors. Prefer monitors:read / monitors:write.
Device health and inventory facts #
text
GET /api/developer/devices/{device_hash}/class-monitoring/
GET /api/developer/devices/{device_hash}/disk-space-history/
GET /api/developer/devices/{device_hash}/inventory-facts/
POST /api/developer/devices/{device_hash}/inventory-facts/Class monitoring returns results with the class's linked monitors. Disk history returns device_hash and chronological history; limit defaults to 180 and is capped at 800.
Inventory facts returns facts, including each slot's observed value, status, approval state, and can_confirm. Confirm an eligible slot with {"slot": "hw.board_serial"} and developer:devices:write. Confirmation is a write, not a new hardware measurement. The inventory feature must be available for the device.
Device object fields #
Device list responses include fields such as:
| Field | Description |
|---|---|
hash_id | Device identifier for API calls |
name / vendor_name | Display name |
hostname | Device hostname |
is_online | Online indicator |
status | Device status string |
device_class | Associated device class |
tag_names / vendor_tag_names | Fleet tags |
last_heartbeat | Last agent heartbeat timestamp |
developer_serial | Optional 16-char alphanumeric serial |
current_firmware_version | Firmware version string |
See the interactive reference for the typed developer device response. Software and OS image versions are separate; legacy firmware-named fields remain compatibility aliases.