Ability™ Developer Portal v23.1
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# Device APIs

The following APIs can be used to interact with the devices in a tenant, and their associated grants and connectivity providers.

# GET Query Devices

# /devices

# Parameters

Name Located in Description Required Schema
ipId query Identity provider identifier No string
IDs query Device identifiers No [ string ]
identity query Search by an external identity of a device No string
tags query Search by one or more tags No [ string ]
tenantId query Search by a tenant id that owns this device No string
solutionId query Search by solution identifier No string
parentId query Search by a parent id of this device No string
connectivityProviderId query Search by connectivity provider identifier No string
grantId query Search by a grant id that this device has No string
limit query Limit the number of returned values No integer

# Responses

Code Description Schema
200 Success ListResponse.Device
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# POST Add a Device

# /devices

# Responses

Code Description Schema
201 Resource created InlineResponse201
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
409 Conflict ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# GET Get a Device by ID

# /devices/{deviceId}

# Parameters

Name Located in Description Required Schema
deviceId path Device identifier Yes string

# Responses

Code Description Schema
200 Found Device
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# PUT Update a Device

# /devices/{deviceId}

# Parameters

Name Located in Description Required Schema
deviceId path Device identifier Yes string

# Responses

Code Description Schema
204 Success
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
409 Conflict ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# DELETE Delete a Device

# /devices/{deviceId}

# Parameters

Name Located in Description Required Schema
deviceId path Device identifier Yes string

# Responses

Code Description Schema
204 Success
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# GET Find a Device by Parent and Path

# /devices/{deviceId}/children

# Parameters

Name Located in Description Required Schema
deviceId path Device identifier Yes string
path query Device path Yes string

# Responses

Code Description Schema
200 Found Device
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# GET Query Grants of a Device

# /devices/{deviceId}/grants/{scope}

# Parameters

Name Located in Description Required Schema
deviceId path Device identifier Yes string
scope path Yes string

# Responses

Code Description Schema
200 Success ListResponse.Grant
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# PUT Assign a Grant

NOTE

This endpoint is idempotent.

# /devices/{deviceId}/grants/{scope}/{grantId}

# Parameters

Name Located in Description Required Schema
deviceId path Device identifier Yes string
scope path Yes string
grantId path Grant identifier Yes string

# Responses

Code Description Schema
204 Success
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# DELETE Revoke a Grant

NOTE

This endpoint is idempotent

# /devices/{deviceId}/grants/{scope}/{grantId}

# Parameters

Name Located in Description Required Schema
deviceId path Device identifier Yes string
scope path Yes string
grantId path Grant identifier Yes string

# Responses

Code Description Schema
204 Success
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# DELETE Disconnect a Connectivity Provider

# /devices/{deviceId}/connectivityProvider/{cpId}

# Parameters

Name Located in Description Required Schema
cpId path Yes string
deviceId path Yes string

# Responses

Code Description Schema
204 Disconnected
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
409 Conflict ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# GET Find a Connectivity Provider and Path

NOTE

If a device is not found or not connected, returns a 404 error.

# /devices/{deviceId}/connectivity

# Parameters

Name Located in Description Required Schema
deviceId path Yes string

# Responses

Code Description Schema
200 Found DeviceConnectivity
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors

# PUT Associate a Connectivity Provider

NOTE Device must belong to a tenant and a solution in order to be

connected.

# /devices/connectivityProvider

# Parameters

Name Located in Description Required Schema
existing query No boolean

# Responses

Code Description Schema
200 Found ConnectivityProvider
400 Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc ServiceErrors
401 Not Authorized. Either the Access token is missing or the access token validation failed
403 Access Forbidden. Requesting entity does not have enough permissions to access the resource
404 Not found. One or more resources were not found, response may contain details about missing resources ServiceErrors
429 Too many requests - indicates the user has sent too many requests in a given amount of time
500 Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors ServiceErrors
Last updated: 1/10/2022, 11:05:26 AM

← Grants →

Feedback