Devices API v3

This page lists every endpoint of the Devices API v3, the credential each one expects, and the request and response conventions. Use it with the live OpenAPI spec when you build device firmware, factory tooling or provisioning scripts.

Base URL and specification

The spec is OpenAPI 3.0.1. Generate a client from it with any OpenAPI generator, as described in Public API.

The Devices API is for devices and the tools that onboard them. To manage your fleet, users and data, use the Public API.

Credentials

Every credential travels in the request, never in the URL. Bearer credentials use the Authorization: Bearer <value> header.

A device JWT or a provisioning key is never accepted by the Public API.

Endpoints

In the table, {P} stands for /api/v3/projects/{project_id}/regions/{region_id}. The region ID is 1 unless you were told otherwise.

Provisioning

Request body for both provisioning methods:

POST /api/v3/provision HTTP/1.1
Host: devices.fundamentum-iot.com
Content-Type: application/json

{
  "project_id": <project-id>,
  "region_id": 1,
  "registry_id": <registry-id>,
  "serial_number": "<serial-number>",
  "asset_type_id": 2,
  "access_token": "<registry-token>",
  "algorithm": "RS256",
  "secret": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}

A successful response returns the device configuration and where to connect:

{
  "status": "success",
  "data": {
    "configuration": {},
    "mqtt": { "host": "mqtts.fundamentum-iot.com", "port": 8883 }
  }
}

If the device already exists, POST answers:

{
  "status": "error",
  "message": "Authorization conflict",
  "data": { "error": "device already provisioned" }
}

Re-provisioning is always an explicit step: use PUT only when you mean to replace the key. See Self-provisioning.

The registry token file contains server_url, mqtt_host, mqtt_port, token, project_id, region_id and registry_id.

Devices

Telemetry over HTTPS is the alternative to MQTT for devices that cannot keep a connection open. See HTTPS alternative.

curl -X POST "https://devices.fundamentum-iot.com/api/v3/projects/<project-id>/regions/1/registries/<registry-id>/devices/<serial-number>/telemetry" \
  -H "Authorization: Bearer $DEVICE_JWT" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 21.4}'

Shelf devices

Shelf devices are pre-registered at the factory with a provisioning key, then assigned to a registry later. See Shelf devices and provisioning keys.

Provisioning keys

start_at and end_at are dates in YYYY-MM-DD format, read as midnight UTC. A key is active when start_at ≤ now < end_at. The key itself is a UUID.

Serial numbers

• Lowercase letters, digits, - and _.
• Unique within a registry, and compared without regard to case.
• Asset type IDs are positive integers. Negative values are reserved.

Responses and errors

Responses use the status/data envelope described in Conventions.

Other versions

Each version publishes its spec at /api/{version}/swagger.json. See Changelog and deprecations.

What's next

• Provisioning
• Connect over MQTTS
• MQTT topics and message formats