Iot Hub Resource - Test Route

Service:

IoT Hub

API Version:

2026-11-01

Test the new route for this Iot Hub

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Devices/IotHubs/{iotHubName}/routing/routes/$testnew?api-version=2026-11-01

URI Parameters

Name	In	Required	Type	Description
iotHubName	path	True	string
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string (uuid)	The ID of the target subscription. The value must be an UUID.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
route	True	RouteProperties	Route properties
message		RoutingMessage	Routing message
twin		RoutingTwin	Routing Twin Reference

Responses

Name	Type	Description
200 OK	TestRouteResult	Azure operation completed successfully.
Other Status Codes	ErrorDetails	An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

IotHubResource_TestRoute

Sample request

HTTP

POST https://management.azure.com/subscriptions/91d12660-3dec-467a-be2a-213b5544ddc0/resourceGroups/myResourceGroup/providers/Microsoft.Devices/IotHubs/testHub/routing/routes/$testnew?api-version=2026-11-01

{
  "message": {
    "appProperties": {
      "key1": "value1"
    },
    "body": "Body of message",
    "systemProperties": {
      "key1": "value1"
    }
  },
  "route": {
    "name": "Routeid",
    "endpointNames": [
      "id1"
    ],
    "isEnabled": true,
    "source": "DeviceMessages"
  }
}

Sample response

Status code:

200

{
  "result": "false",
  "details": {
    "compilationErrors": [
      {
        "location": {
          "end": {
            "column": 24,
            "line": 12
          },
          "start": {
            "column": 12,
            "line": 12
          }
        },
        "message": "string response",
        "severity": "error"
      }
    ]
  }
}

Definitions

Name	Description
ErrorDetails	Error details.
RouteCompilationError	Compilation error when evaluating route
RouteErrorPosition	Position where the route error happened
RouteErrorRange	Range of route errors
RouteErrorSeverity	Severity of the route error
RouteProperties	The properties of a routing rule that your IoT hub uses to route messages to endpoints.
RoutingMessage	Routing message
RoutingSource	The source that the routing rule is to be applied to, such as DeviceMessages.
RoutingTwin	Twin reference input parameter. This is an optional parameter
RoutingTwinProperties
TestResultStatus	Result of testing route
TestRouteInput	Input for testing route
TestRouteResult	Result of testing one route
TestRouteResultDetails	Detailed result of testing a route

ErrorDetails

Object

Error details.

Name	Type	Description
code	string	The error code.
details	string	The error details.
httpStatusCode	string	The HTTP status code.
message	string	The error message.

RouteCompilationError

Object

Compilation error when evaluating route

Name	Type	Description
location	RouteErrorRange	Location where the route error happened
message	string	Route error message
severity	RouteErrorSeverity	Severity of the route error

RouteErrorPosition

Object

Position where the route error happened

Name	Type	Description
column	integer (int32)	Column where the route error happened
line	integer (int32)	Line where the route error happened

RouteErrorRange

Object

Range of route errors

Name	Type	Description
end	RouteErrorPosition	End where the route error happened
start	RouteErrorPosition	Start where the route error happened

RouteErrorSeverity

Enumeration

Severity of the route error

Value	Description
error	error
warning	warning

RouteProperties

Object

The properties of a routing rule that your IoT hub uses to route messages to endpoints.

Name	Type	Description
condition	string	The condition that is evaluated to apply the routing rule. If no condition is provided, it evaluates to true by default. For grammar, see: https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-query-language
endpointNames	string[]	The list of endpoints to which messages that satisfy the condition are routed. Currently only one endpoint is allowed.
isEnabled	boolean	Used to specify whether a route is enabled.
name	string pattern: ^[A-Za-z0-9-._]{1,64}$	The name of the route. The name can only include alphanumeric characters, periods, underscores, hyphens, has a maximum length of 64 characters, and must be unique.
source	RoutingSource	The source that the routing rule is to be applied to, such as DeviceMessages.

RoutingMessage

Object

Routing message

Name	Type	Description
appProperties	object	App properties
body	string	Body of routing message
systemProperties	object	System properties

RoutingSource

Enumeration

The source that the routing rule is to be applied to, such as DeviceMessages.

Value	Description
Invalid	Invalid
DeviceMessages	DeviceMessages
TwinChangeEvents	TwinChangeEvents
DeviceLifecycleEvents	DeviceLifecycleEvents
DeviceJobLifecycleEvents	DeviceJobLifecycleEvents
DeviceConnectionStateEvents	DeviceConnectionStateEvents

RoutingTwin

Object

Twin reference input parameter. This is an optional parameter

Name	Type	Description
properties	RoutingTwinProperties
tags	management.azure.com.iothub.iothubresource.testroute	Twin Tags

RoutingTwinProperties

Object

Name	Type	Description
desired	management.azure.com.iothub.iothubresource.testroute	Twin desired properties
reported	management.azure.com.iothub.iothubresource.testroute	Twin reported properties

TestResultStatus

Enumeration

Result of testing route

Value	Description
undefined	undefined
false	false
true	true

TestRouteInput

Object

Input for testing route

Name	Type	Description
message	RoutingMessage	Routing message
route	RouteProperties	Route properties
twin	RoutingTwin	Routing Twin Reference

TestRouteResult

Object

Result of testing one route

Name	Type	Description
details	TestRouteResultDetails	Detailed result of testing route
result	TestResultStatus	Result of testing route

TestRouteResultDetails

Object

Detailed result of testing a route

Name	Type	Description
compilationErrors	RouteCompilationError[]	JSON-serialized list of route compilation errors