Azure IoT Central API Reference

API Overview

The Azure IoT Central API allows you to programmatically interact with your IoT Central applications. You can manage devices, applications, users, rules, dashboards, and much more. This documentation provides a reference for the available REST API endpoints.

All API requests must be made over HTTPS and directed to: https://your-iot-central-app.azureiotcentral.com/api/v1

API versions are specified in the URL. For example: https://your-iot-central-app.azureiotcentral.com/api/devices

For detailed information on specific operations, please refer to the sections below.

Authentication

All requests to the IoT Central API must be authenticated. Currently, the API supports token-based authentication using API tokens.

You can generate API tokens within your IoT Central application's settings under "API tokens". These tokens have specific roles and permissions assigned to them.

When making an API request, include an Authorization header with your token:

Authorization: Bearer YOUR_API_TOKEN

Replace YOUR_API_TOKEN with the actual API token generated from your IoT Central application.

Applications

Endpoints for managing your IoT Central application.

Get Application Details

GET /api/apps/app

Retrieves information about the current IoT Central application.

Parameters

Name	Type	Description
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Success Response (200 OK)

{
  "id": "your-app-id",
  "displayName": "My IoT Application",
  "template": "iotc-default",
  "location": "East US",
  "state": "Running",
  "createdTime": "2023-01-15T10:30:00Z",
  "lastUpdatedTime": "2023-10-26T14:00:00Z"
}

Devices

Endpoints for managing devices registered in your IoT Central application.

List Devices

GET /api/devices

Retrieves a list of all devices in the application.

Parameters

Name	Type	Description
`api-version`	string	Specifies the API version. Example: `2022-07-31`.
`$filter`	string	Optional. Filter the results (e.g., `simulated eq true`).
`$top`	integer	Optional. Maximum number of devices to return.

Success Response (200 OK)

{
  "devices": [
    {
      "id": "device001",
      "displayName": "Sensor Alpha",
      "template": "dtmi:com:example:temperatureSensor;1",
      "simulated": false,
      "provisioned": true,
      "enabled": true
    },
    {
      "id": "device002",
      "displayName": "Actuator Beta",
      "template": "dtmi:com:example:actuator;1",
      "simulated": true,
      "provisioned": true,
      "enabled": true
    }
  ]
}

Create Device

PUT /api/devices/{deviceId}

Creates a new device in the IoT Central application.

Parameters

Name	Type	Description
`deviceId`	string	The unique identifier for the new device.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Request Body

A JSON object containing device details.

{
  "displayName": "New IoT Device",
  "template": "dtmi:com:example:genericDevice;1",
  "simulated": false
}

Success Response (200 OK)

Returns the created device object.

Error Response (409 Conflict)

If a device with the specified ID already exists.

Get Device

GET /api/devices/{deviceId}

Retrieves details for a specific device.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device to retrieve.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Success Response (200 OK)

{
      "id": "device001",
      "displayName": "Sensor Alpha",
      "template": "dtmi:com:example:temperatureSensor;1",
      "simulated": false,
      "provisioned": true,
      "enabled": true,
      "lastSeen": "2023-10-26T15:00:00Z",
      "firmwareVersion": "1.2.0"
    }

Error Response (404 Not Found)

If the device with the specified ID does not exist.

Update Device

PATCH /api/devices/{deviceId}

Updates properties of an existing device.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device to update.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Request Body

A JSON object containing the properties to update.

{
  "displayName": "Updated Sensor Alpha",
  "enabled": false
}

Success Response (200 OK)

Returns the updated device object.

Error Response (404 Not Found)

If the device with the specified ID does not exist.

Delete Device

DELETE /api/devices/{deviceId}

Deletes a device from the IoT Central application.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device to delete.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Success Response (204 No Content)

Error Response (404 Not Found)

If the device with the specified ID does not exist.

Telemetry

Endpoints for sending and managing device telemetry.

Send Telemetry

POST /api/devices/{deviceId}/telemetry

Sends telemetry data from a device to IoT Central.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device sending telemetry.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Request Body

A JSON object representing the telemetry event. The structure depends on the device template.

{
  "temperature": 25.5,
  "humidity": 60.2,
  "timestamp": "2023-10-26T15:05:10Z"
}

Success Response (204 No Content)

Error Response (400 Bad Request)

If the telemetry data format is invalid.

Error Response (404 Not Found)

If the device with the specified ID does not exist.

Commands

Endpoints for invoking and managing device commands.

Trigger Command

POST /api/devices/{deviceId}/commands/{commandName}

Triggers a command on a specific device.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device to target.
`commandName`	string	The name of the command to trigger (from the device template).
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Request Body

An optional JSON object containing command arguments, if required by the command definition.

{
  "rebootInterval": 60
}

Success Response (200 OK)

Returns the status of the command execution.

{
      "commandId": "cmd-12345",
      "status": "Pending"
    }

Error Response (400 Bad Request)

If command arguments are invalid or missing.

Error Response (404 Not Found)

If the device or command is not found.

Get Command Status

GET /api/devices/{deviceId}/commands/{commandId}/status

Retrieves the status of a previously triggered command.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device that received the command.
`commandId`	string	The unique identifier of the command.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Success Response (200 OK)

{
      "commandId": "cmd-12345",
      "status": "Completed",
      "result": "Device rebooted successfully.",
      "completedTime": "2023-10-26T15:15:00Z"
    }

Error Response (404 Not Found)

If the command or device is not found.

Properties

Endpoints for interacting with device properties (reported and desired).

Get Properties

GET /api/devices/{deviceId}/properties/{propertyName}

Retrieves the value of a specific property for a device.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device.
`propertyName`	string	The name of the property to retrieve.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Success Response (200 OK)

{
      "value": "1.2.0",
      "lastReportedTime": "2023-10-26T15:20:00Z"
    }

Error Response (404 Not Found)

If the device or property is not found.

Update Properties

PATCH /api/devices/{deviceId}/properties/{propertyName}

Updates the value of a desired property for a device.

Parameters

Name	Type	Description
`deviceId`	string	The ID of the device.
`propertyName`	string	The name of the desired property to update.
`api-version`	string	Specifies the API version. Example: `2022-07-31`.

Request Body

A JSON object containing the new value for the property.

{
  "value": "1.3.0"
}

Success Response (200 OK)

Returns the updated property object.

Error Response (400 Bad Request)

If the new property value is invalid.

Error Response (404 Not Found)

If the device or property is not found.