Skip to content

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:

FieldMaps toDescription
namevendor_nameDisplay name
descriptionvendor_descriptionDevice description
wormhole_enabled-Enable/disable Wormhole
wormhole_override-Wormhole configuration override
application_location / assigned_locationDevice metadataValidated 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:

FieldDescription
hash_idDevice identifier for API calls
name / vendor_nameDisplay name
hostnameDevice hostname
is_onlineOnline indicator
statusDevice status string
device_classAssociated device class
tag_names / vendor_tag_namesFleet tags
last_heartbeatLast agent heartbeat timestamp
developer_serialOptional 16-char alphanumeric serial
current_firmware_versionFirmware 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.