Overview

Most of the core functionality provided by the SiteWhere APIs is accessible externally via REST services. Using the services, an external entity can create, view, update, or delete entities in the system. The services can also interact with subsystems such as asset management. All REST calls are subject to authentication and use the permissions model to verify that the authenticated user is authorized for the operation.

SiteWhere Server includes a working version of Swagger which adds a user interface around the REST services. Using the Swagger interface, users can interactively execute REST calls against a running SiteWhere instance and view the JSON responses.

The documentation that follows covers the functionality provided by the services including the URL path used to execute the method, parameters needed to supply information to the invocation, and examples of the request and/or response payloads.

Calling SiteWhere REST Services

SiteWhere REST services can be invoked by submitting an HTTP request to the proper URI for the specified operation. An example of a valid HTTP request-response interaction is captured below:

GET /sitewhere/api/sites HTTP/1.1
Authorization: Basic YWRtaW46cGFzc3dvcmQ=
X-SiteWhere-Tenant: sitewhere1234567890

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: max-age=0,no-cache,no-store,post-check=0,pre-check=0
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 14 Oct 2015 13:00:23 GMT

{"numResults":1,"results":[{"createdDate":"2015-10-13T12:41:04.061-0400","createdBy":"system","updatedDate":null,"deleted":false,"token":"bb105f8d-3150-41f5-b9d1-db04965668d3","name":"Construction Site 1","description":"A construction site with many high-value assets that should not be taken offsite. The system provides location tracking for the assets and notifies administrators if any of the assets move outside of the general site area or into areas where they are not allowed.","imageUrl":"https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg","map":{"type":"mapquest","metadata":{"centerLongitude":"-84.23966646194458","centerLatitude":"34.10469794977326","zoomLevel":"15"}},"metadata":{}}]}

HTTP Verbs

SiteWhere REST services follow the standard pattern of using HTTP verbs to indicate the type of operation to be performed as detailed below:

GET - Get information about a given resource. The result will be in the form of an entity or list of entities. Many list operations return responses in the form of search results that include the number of matching records and the list of matching results.
POST - Create a new resource or cause an effect on some part of the system. Most POST operations return an entity that is the result of the effect of the submission.
PUT - Update an existing resource with new information. The general pattern with updates is to only submit the fields that changed. Not passing a given field leaves the existing value as-is.
DELETE - Deletes an existing entity from the system. Most entities support either a forced delete which deletes the entity from the datastore or a marked delete which flags the entity as deleted. See delete policies for more information.

Required Headers

Certain headers are required as part of the HTTP request in order for SiteWhere to process it properly. They include:

Authorization - Basic authentication is used to identify the user accessing the REST resource. The value passed must match credentials for a user in the system that has access to the given resource. If not authenticated, the response status code will be 403.
X-SiteWhere-Tenant - The authentication token for the tenant that the operation is to occur on. The authenticated user must have permissions to access the given tenant. Another option for passing the tenant auth token is to send a request parameter named tenantAuthToken with the value. Not passing the token will result in a response status code of 401.

Paged Results

Many SiteWhere REST operations can result in a response that contains a very large number of entities. When dealing with large domains, result sets can contain thousands or millions of results. Rather than returning all results, SiteWhere employs a consistent paging scheme for all list-oriented methods. Two parameters are passed for any method that uses paging:

page - The page number in the result set. This is used in conjunction with the page size to calculate the starting record to return. The default page number is 1 which points to the beginning of the result set.
pageSize - The number of records that is considered a page. The default page size is 100 records.

Clients that use the rest service can weigh out which page size makes sense for the specific application. Small page sizes result in faster calls with less data, but require more calls to process the result set. Large page sizes result in slower calls with more data, but are more efficient in terms of HTTP overhead and total network traffic.

Asset Management

SiteWhere assets represent objects in the physical world – people, places, and things. Device specification assets are used to describe the hardware information/configuration for a type of device. Device assignment assets are used to describe an entity associated with a device – a person associated with a badge, a bulldozer associated with a location tracker, or a hospital ward associated with a piece of hospital equipment.

Asset Modules

Rather than hard-coding a schema for assets in the system, SiteWhere defines SPIs for general asset types and allows asset modules to be plugged in to provide asset definitions. This allows existing identity management systems to be used in providing a list of available person assets. It also allows product catalog systems to be used in defining available hardware assets. Assets loaded from XML files or external systems are treated as read-only and can not be edited from within the administrative console.

Asset Categories

SiteWhere also provides the concept of asset categories which reside in the SiteWhere datastore. Asset categories are containers for assets of a given type and may be added/edited from within the administrative console. Asset categories are loaded as asset modules at runtime, allowing assets to be pulled from the datastore in addition to modules loaded from other sources such as XML files or third-party systems.

Create a New Asset Category

Creates a new asset category that acts as a container for a specific type of assets. Asset categories can be edited via the SiteWhere administrative interface and are loaded at runtime as asset modules that can be referenced by specifications or device assignments.

Request URI

POST/sitewhere/api/assets/categories

The category id should be a unique value not already being used by another module. The system will allow a category to be created with an id that matches an existing module. In this case, when the system creates an asset module for the category, it will mask the existing module. This is allowed for purposes of testing when systems for external asset modules are not available. Category ids must be alphanumeric and can contain dashes or underscores.

{
  "id" : "my-devices",
  "name" : "My Devices",
  "assetType" : "Device"
}Request

Create a New Hardware Asset in Category

Creates a new hardware asset in an asset category. Note that the assetType of the given asset category must be Hardware or Device or an error will result.

Request URI

POST/sitewhere/api/assets/categories/{categoryId}/hardware

Path Parameters

Name	Description
categoryId	Unique category id

{
  "id" : "303",
  "name" : "Caterpillar 320E L Excavator",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/cat/cat-320e.jpg",
  "properties" : {
    "operating.weight" : "54450",
    "net.power" : "153",
    "fuel.tank" : "108.3",
    "manufacturer" : "Caterpillar"
  },
  "sku" : "CAT-320E-L",
  "description" : "A great all-around excavator, the 320E is easy to maneuver, yet powerful enough to handle tough jobs. Lift capacity has been improved by 5 percent on the standard machine and up to 20 percent on the Heavy Lift configuration. A lower emissions engine boosts fuel efficiency, while other new features enhance safety and productivity, cut service time and reduce operating costs."
}Request

Create a New Location Asset in Category

Creates a new location asset in an asset category. Note that the assetType of the given asset category must be Location or an error will result.

Request URI

POST/sitewhere/api/assets/categories/{categoryId}/locations

Path Parameters

Name	Description
categoryId	Unique category id

{
  "id" : "ct1",
  "name" : "Construction Trailer",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/trailer.jpg",
  "properties" : {
    "worksite.id" : "GA-ATL-101-Peachtree"
  },
  "latitude" : 33.755,
  "longitude" : -84.39
}Request

Create a New Person Asset in Category

Create a new person asset in a given asset category. Note that the assetType of the given asset category must be Person or an error will result.

Request URI

POST/sitewhere/api/assets/categories/{categoryId}/persons

Path Parameters

Name	Description
categoryId	Unique category id

{
  "id" : "derek",
  "name" : "Derek Adams",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "properties" : {
    "phone.number" : "777-555-1212"
  },
  "userName" : "dadams",
  "emailAddress" : "dadams@demoserver.com",
  "roles" : [ "dev" ]
}Request

Delete an Existing Asset Category

Delete an existing asset category based on its unique id.

This operation will delete all assets from the category.

Request URI

DELETE/sitewhere/api/assets/categories/{categoryId}

Path Parameters

Name	Description
categoryId	Unique category id

{
  "id" : "my-devices",
  "name" : "My Devices",
  "assetType" : "Device"
}Response

Delete an Existing Category Asset

Delete an existing asset from an asset category. The response contains information about the asset that was deleted.

Request URI

DELETE/sitewhere/api/assets/categories/{categoryId}/assets/{assetId}

Path Parameters

Name	Description
assetId	Unique asset id
categoryId	Unique category id

If the asset deleted was a person asset, the response will resemble the output below:

{
  "id" : "derek",
  "name" : "Derek Adams",
  "type" : "Person",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "properties" : {
    "phone.number" : "777-555-1212"
  },
  "userName" : "dadams",
  "emailAddress" : "dadams@demoserver.com",
  "roles" : [ "dev" ]
}Response

If the asset deleted was a hardware asset, the response will resemble the output below:

{
  "id" : "303",
  "name" : "Caterpillar 320E L Excavator",
  "type" : "Hardware",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/cat/cat-320e.jpg",
  "properties" : {
    "operating.weight" : "54450",
    "net.power" : "153",
    "fuel.tank" : "108.3",
    "manufacturer" : "Caterpillar"
  },
  "sku" : "CAT-320E-L",
  "description" : "A great all-around excavator, the 320E is easy to maneuver, yet powerful enough to handle tough jobs. Lift capacity has been improved by 5 percent on the standard machine and up to 20 percent on the Heavy Lift configuration. A lower emissions engine boosts fuel efficiency, while other new features enhance safety and productivity, cut service time and reduce operating costs."
}Response

If the asset deleted was a location asset, the response will resemble the output below:

{
  "id" : "ct1",
  "name" : "Construction Trailer",
  "type" : "Location",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/trailer.jpg",
  "properties" : {
    "worksite.id" : "GA-ATL-101-Peachtree"
  },
  "latitude" : 33.755,
  "longitude" : -84.39
}Response

Get a Category Asset by Unique Id

Get an asset from a category based on unique id. The format of the response depends on the type of asset.

Request URI

GET/sitewhere/api/assets/categories/{categoryId}/assets/{assetId}

Path Parameters

Name	Description
assetId	Unique asset id
categoryId	Unique category id

If the asset returned is a person asset, the response will resemble the output below:

{
  "id" : "derek",
  "name" : "Derek Adams",
  "type" : "Person",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "properties" : {
    "phone.number" : "777-555-1212"
  },
  "userName" : "dadams",
  "emailAddress" : "dadams@demoserver.com",
  "roles" : [ "dev" ]
}Response

If the asset returned is a hardware asset, the response will resemble the output below:

{
  "id" : "303",
  "name" : "Caterpillar 320E L Excavator",
  "type" : "Hardware",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/cat/cat-320e.jpg",
  "properties" : {
    "operating.weight" : "54450",
    "net.power" : "153",
    "fuel.tank" : "108.3",
    "manufacturer" : "Caterpillar"
  },
  "sku" : "CAT-320E-L",
  "description" : "A great all-around excavator, the 320E is easy to maneuver, yet powerful enough to handle tough jobs. Lift capacity has been improved by 5 percent on the standard machine and up to 20 percent on the Heavy Lift configuration. A lower emissions engine boosts fuel efficiency, while other new features enhance safety and productivity, cut service time and reduce operating costs."
}Response

If the asset returned is a location asset, the response will resemble the output below:

{
  "id" : "ct1",
  "name" : "Construction Trailer",
  "type" : "Location",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/trailer.jpg",
  "properties" : {
    "worksite.id" : "GA-ATL-101-Peachtree"
  },
  "latitude" : 33.755,
  "longitude" : -84.39
}Response

Get an Asset by Unique Id

Search an asset module for an asset with the given id.

Request URI

GET/sitewhere/api/assets/modules/{assetModuleId}/assets/{assetId}

Path Parameters

Name	Description
assetId	Unique asset id
assetModuleId	Unique asset module id

If the asset returned is a person asset, the response will resemble the output below:

{
  "id" : "derek",
  "name" : "Derek Adams",
  "type" : "Person",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "properties" : {
    "phone.number" : "777-555-1212"
  },
  "userName" : "dadams",
  "emailAddress" : "dadams@demoserver.com",
  "roles" : [ "dev" ]
}Response

If the asset returned is a hardware asset, the response will resemble the output below:

{
  "id" : "303",
  "name" : "Caterpillar 320E L Excavator",
  "type" : "Hardware",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/cat/cat-320e.jpg",
  "properties" : {
    "operating.weight" : "54450",
    "net.power" : "153",
    "fuel.tank" : "108.3",
    "manufacturer" : "Caterpillar"
  },
  "sku" : "CAT-320E-L",
  "description" : "A great all-around excavator, the 320E is easy to maneuver, yet powerful enough to handle tough jobs. Lift capacity has been improved by 5 percent on the standard machine and up to 20 percent on the Heavy Lift configuration. A lower emissions engine boosts fuel efficiency, while other new features enhance safety and productivity, cut service time and reduce operating costs."
}Response

If the asset returned is a location asset, the response will resemble the output below:

{
  "id" : "ct1",
  "name" : "Construction Trailer",
  "type" : "Location",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/trailer.jpg",
  "properties" : {
    "worksite.id" : "GA-ATL-101-Peachtree"
  },
  "latitude" : 33.755,
  "longitude" : -84.39
}Response

Get an Asset Category by Unique Id

Given the id of an existing asset category, returns the information for the category.

Request URI

GET/sitewhere/api/assets/categories/{categoryId}

Path Parameters

Name	Description
categoryId	Unique category id

{
  "id" : "my-devices",
  "name" : "My Devices",
  "assetType" : "Device"
}Response

Get an Asset Module by Unique Id

Get details about an asset module based on the unique asset module id. The response includes just the basic information about a module such as its name and the type of assets it contains.

Request URI

GET/sitewhere/api/assets/modules/{assetModuleId}

Path Parameters

Name	Description
assetModuleId	Unique asset module id

{
  "id" : "ac-persons",
  "name" : "Default Identity Management",
  "assetType" : "Person"
}Response

List Asset Categories that Match Criteria

List all asset categories that match the given criteria.

Request URI

GET/sitewhere/api/assets/categories

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

[ {
  "id" : "my-devices",
  "name" : "My Devices",
  "assetType" : "Device"
}, {
  "id" : "developers",
  "name" : "Developers",
  "assetType" : "Person"
} ]Response

List Asset Modules that Match Criteria

List all asset modules or filter modules based on the type of asset hosted by the module.

Request URI

GET/sitewhere/api/assets/modules

Request Parameters

Name	Description	Required
assetType	Asset type	false

[ {
  "id" : "ac-persons",
  "name" : "Default Identity Management",
  "assetType" : "Person"
}, {
  "id" : "ac-devices",
  "name" : "Default Device Management",
  "assetType" : "Device"
} ]Response

List Assignments Associated with an Asset

Find all assignments that are associated with a given asset. If no assignment status is provided, the entire history of associations will be returned, whether currently associated or not.

Request URI

GET/sitewhere/api/assets/modules/{assetModuleId}/assets/{assetId}/assignments

Path Parameters

Name	Description
assetId	Unique asset id
assetModuleId	Unique asset module id

Request Parameters

Name	Description	Required
siteToken	Limit results to the given site	false
status	Limit results to the given status	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.114-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "status" : "Active",
    "activeDate" : "2016-12-10T13:11:45.114-0500",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.124-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "d8c5c9f8-2b48-448d-89a4-4906ced63779",
    "deviceHardwareId" : "bfca26f1-2b33-449c-8335-78ff5852e326",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "status" : "Active",
    "activeDate" : "2016-12-10T13:11:45.124-0500",
    "metadata" : { }
  } ]
}Response

List Category Assets that Match Criteria

List assets from an asset category that match the given criteria.

Request URI

GET/sitewhere/api/assets/categories/{categoryId}/assets

Path Parameters

Name	Description
categoryId	Unique category id

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "derek",
    "name" : "Derek Adams",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "properties" : {
      "phone.number" : "777-555-1212"
    },
    "userName" : "dadams",
    "emailAddress" : "dadams@demoserver.com",
    "roles" : [ "dev" ]
  }, {
    "id" : "martin",
    "name" : "Martin Weber",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/martin.jpg",
    "properties" : {
      "phone.number" : "777-770-1212"
    },
    "userName" : "mweber",
    "emailAddress" : "martin@demoserver.com",
    "roles" : [ "busdev" ]
  } ]
}Response

Refresh the List of Asset Modules

Refreshes the list of asset modules. This includes querying the list of asset categories and reloading them from the database into asset modules. This also includes calling the refresh() method on each external module, which generally forces a reload of data from the underlying datastore.

Request URI

POST/sitewhere/api/assets/modules/refresh

[ {
  "result" : "Successful",
  "message" : "Module loaded successfully."
}, {
  "result" : "Failed",
  "message" : "Module failed to refresh."
} ]Response

Search for Assets in an Asset Module

Performs a search of all assets in the asset module and returns the list of matches. The search criteria applies differently depending on asset type. Fields searched for each type are listed below:

Person Assets: Id, Name, Email Address, and Username.
Hardware Assets: Id, Name, and Description.
Location Assets: Name.

Matches are case insensitive.

Request URI

GET/sitewhere/api/assets/modules/{assetModuleId}/assets

Path Parameters

Name	Description
assetModuleId	Unique asset module id

Request Parameters

Name	Description	Required
criteria	Criteria for search	false

{
  "numResults" : 1,
  "results" : [ {
    "id" : "derek",
    "name" : "Derek Adams",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "properties" : {
      "phone.number" : "777-555-1212"
    },
    "userName" : "dadams",
    "emailAddress" : "dadams@demoserver.com",
    "roles" : [ "dev" ]
  } ]
}Response

Update an Existing Asset Category

Updates the existing information for an asset category. Note that the category id and asset type can not be changed once a category has been created.

Request URI

PUT/sitewhere/api/assets/categories/{categoryId}

Path Parameters

Name	Description
categoryId	Unique category id

{
  "id" : "my-devices",
  "name" : "My Updated Devices",
  "assetType" : "Device"
}Request

Update an Existing Hardware Asset in Category

Updates an existing hardware asset in an asset category. Note that the unique id of an asset can not be changed once it exists in the system.

Request URI

PUT/sitewhere/api/assets/categories/{categoryId}/hardware/{assetId}

Path Parameters

Name	Description
assetId	Unique asset id
categoryId	Unique category id

{
  "name" : "Caterpillar 320E L Excavator",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/cat/cat-320e.jpg",
  "properties" : {
    "operating.weight" : "54450",
    "net.power" : "153",
    "fuel.tank" : "108.3",
    "manufacturer" : "Caterpillar"
  },
  "sku" : "CAT-320E-L",
  "description" : "A great all-around excavator, the 320E is easy to maneuver, yet powerful enough to handle tough jobs. Lift capacity has been improved by 5 percent on the standard machine and up to 20 percent on the Heavy Lift configuration. A lower emissions engine boosts fuel efficiency, while other new features enhance safety and productivity, cut service time and reduce operating costs."
}Request

Update an Existing Location Asset in Category

Updates an existing location asset in an asset category. Note that the unique id of an asset can not be changed once it exists in the system.

Request URI

PUT/sitewhere/api/assets/categories/{categoryId}/locations/{assetId}

Path Parameters

Name	Description
assetId	Unique asset id
categoryId	Unique category id

{
  "name" : "Construction Trailer",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/trailer.jpg",
  "properties" : {
    "worksite.id" : "GA-ATL-101-Peachtree"
  },
  "latitude" : 33.755,
  "longitude" : -84.39
}Request

Update an Existing Person Asset in Category

Updates an existing person asset in a given asset category. Note that the unique id of an asset can not be changed once it exists in the system.

Request URI

PUT/sitewhere/api/assets/categories/{categoryId}/persons/{assetId}

Path Parameters

Name	Description
assetId	Unique asset id
categoryId	Unique category id

{
  "name" : "Derek Adams",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "properties" : {
    "phone.number" : "777-555-1212"
  },
  "userName" : "dadams",
  "emailAddress" : "dadams@demoserver.com",
  "roles" : [ "dev" ]
}Request

Batch Operations

Batch operations are actions that operate on multiple devices, executing asynchronously and providing a mechanism for monitoring progress over time. Examples of batch operations include executing commands on a large number of devices or applying firmware updates to a group of devices. The batch operation manager is responsible for taking a batch operation request and breaking it out into the actions necessary to complete the goal. Since batch operations can result in a large load on the system, the batch operation manager allows for throttling the execution of operations so that a reasonable load is achieved when dealing with thousands or millions of devices.

Create Batch Command Operation Based on Criteria

Creates a batch command invocation operation that targets all devices that meet the given criteria. Criteria can include any combination of:

Devices that implement a given specification
Devices created within a date range
Devices that belong to a device group
Devices that belong to device groups with a given role
Devices that do not have an active assignment

The list of devices is calculated based on the criteria and all matching devices become part of the batch command invocation operation.

Request URI

POST/sitewhere/api/batch/command/criteria

The example below targets devices that implement a given specification and were added to the system within the given date range.

{
  "token" : "438e068c-0dcb-4d96-a35f-06a52b084373",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  },
  "specificationToken" : "2f540b66-b6ab-4fbe-bdf3-ca6aaf103848",
  "startDate" : "2016-12-10T13:11:46.096-0500",
  "endDate" : "2016-12-10T14:11:46.096-0500"
}Request

The example below targets devices that are members of a given device group and do not have an active assignment.

{
  "token" : "438e068c-0dcb-4d96-a35f-06a52b084373",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  },
  "groupToken" : "24288cbd-e8aa-4b35-a6b3-27e24a123718"
}Request

The example below targets devices in device groups that have the given role.

{
  "token" : "438e068c-0dcb-4d96-a35f-06a52b084373",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  },
  "groupsWithRole" : "americas"
}Request

The response is the batch operation that was created. To check the status of the individual commands, use the REST method that lists the batch elements associated with the operation.

{
  "createdDate" : "2016-12-10T13:11:45.125-0500",
  "createdBy" : "admin",
  "updatedDate" : "2016-12-10T13:11:45.125-0500",
  "updatedBy" : "system",
  "deleted" : false,
  "token" : "27f65236-ae80-40fe-8634-3a9781077754",
  "operationType" : "InvokeCommand",
  "parameters" : {
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414"
  },
  "processingStatus" : "FinishedSuccessfully",
  "processingStartedDate" : "2016-12-10T13:11:45.125-0500",
  "processingEndedDate" : "2016-12-10T13:11:45.126-0500",
  "metadata" : {
    "reboot" : "true",
    "interval" : "60"
  }
}Response

Create New Batch Command Invocation

Creates a new batch command invocation which will asynchronously invoke a command on a list of devices. If no token is passed with the request, a new token will be generated automatically.

Request URI

POST/sitewhere/api/batch/command

{
  "token" : "438e068c-0dcb-4d96-a35f-06a52b084373",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  },
  "hardwareIds" : [ "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0", "bfca26f1-2b33-449c-8335-78ff5852e326" ]
}Request

The response is the batch operation that was created. To check the status of the individual commands, use the REST method that lists the batch elements associated with the operation.

{
  "createdDate" : "2016-12-10T13:11:45.125-0500",
  "createdBy" : "admin",
  "updatedDate" : "2016-12-10T13:11:45.125-0500",
  "updatedBy" : "system",
  "deleted" : false,
  "token" : "27f65236-ae80-40fe-8634-3a9781077754",
  "operationType" : "InvokeCommand",
  "parameters" : {
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414"
  },
  "processingStatus" : "FinishedSuccessfully",
  "processingStartedDate" : "2016-12-10T13:11:45.125-0500",
  "processingEndedDate" : "2016-12-10T13:11:45.126-0500",
  "metadata" : {
    "reboot" : "true",
    "interval" : "60"
  }
}Response

Get Batch Operation by Unique Token

Get information about a batch operation given its unique token.

Request URI

GET/sitewhere/api/batch/{batchToken}

Path Parameters

Name	Description
batchToken	Unique token that identifies batch operation

{
  "createdDate" : "2016-12-10T13:11:45.125-0500",
  "createdBy" : "admin",
  "updatedDate" : "2016-12-10T13:11:45.125-0500",
  "updatedBy" : "system",
  "deleted" : false,
  "token" : "27f65236-ae80-40fe-8634-3a9781077754",
  "operationType" : "InvokeCommand",
  "parameters" : {
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414"
  },
  "processingStatus" : "FinishedSuccessfully",
  "processingStartedDate" : "2016-12-10T13:11:45.125-0500",
  "processingEndedDate" : "2016-12-10T13:11:45.126-0500",
  "metadata" : {
    "reboot" : "true",
    "interval" : "60"
  }
}Response

List Batch Operation Elements

List elements for the given batch operation.

Request URI

GET/sitewhere/api/batch/{operationToken}/elements

Path Parameters

Name	Description
operationToken	Unique token that identifies batch operation

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "batchOperationToken" : "27f65236-ae80-40fe-8634-3a9781077754",
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "index" : 0,
    "processingStatus" : "Succeeded",
    "processedDate" : "2016-12-10T13:11:45.126-0500",
    "metadata" : {
      "invocation" : "239402938454"
    }
  }, {
    "batchOperationToken" : "27f65236-ae80-40fe-8634-3a9781077754",
    "hardwareId" : "bfca26f1-2b33-449c-8335-78ff5852e326",
    "index" : 1,
    "processingStatus" : "Unprocessed",
    "metadata" : { }
  } ]
}Response

List Batch Operations

List all batch operations that meet the given criteria.

Request URI

GET/sitewhere/api/batch/

Request Parameters

Name	Description	Required
includeDeleted	Include deleted	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.125-0500",
    "createdBy" : "admin",
    "updatedDate" : "2016-12-10T13:11:45.125-0500",
    "updatedBy" : "system",
    "deleted" : false,
    "token" : "27f65236-ae80-40fe-8634-3a9781077754",
    "operationType" : "InvokeCommand",
    "parameters" : {
      "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414"
    },
    "processingStatus" : "FinishedSuccessfully",
    "processingStartedDate" : "2016-12-10T13:11:45.125-0500",
    "processingEndedDate" : "2016-12-10T13:11:45.126-0500",
    "metadata" : {
      "reboot" : "true",
      "interval" : "60"
    }
  }, {
    "createdDate" : "2016-12-10T13:11:45.127-0500",
    "createdBy" : "admin",
    "updatedDate" : "2016-12-10T13:11:45.127-0500",
    "updatedBy" : "system",
    "deleted" : false,
    "token" : "dcb73dd2-4b3f-4c00-a73a-61b974cae6a9",
    "operationType" : "InvokeCommand",
    "parameters" : {
      "commandToken" : "3c1c61a3-652f-407e-80e7-fcfb13c10624"
    },
    "processingStatus" : "FinishedSuccessfully",
    "processingStartedDate" : "2016-12-10T13:11:45.127-0500",
    "processingEndedDate" : "2016-12-10T13:11:45.127-0500",
    "metadata" : {
      "verbose" : "true"
    }
  } ]
}Response

Schedule Batch Command Operation Based on Criteria

Schedules a batch command invocation operation that targets all devices which meet the given criteria. Criteria can include any combination of:

Devices that implement a given specification
Devices created within a date range
Devices that belong to a device group
Devices that belong to device groups with a given role
Devices that do not have an active assignment

The list of devices is calculated based on the criteria and all matching devices become part of the batch command invocation operation. Since this operation is executed on a schedule, the list of matching elements may vary from on execution to the next based on whether devices meet the criteria at that point in time.

Request URI

POST/sitewhere/api/batch/command/criteria/schedules/{scheduleToken}

Path Parameters

Name	Description
scheduleToken	Schedule token

Device Assignments

Events are not logged directly against devices, since a given device may serve in a number of contexts. For instance, a visitor badge may be assigned to a new person every day. Rather than intermingle event data from all the people a badge has been assigned to, the concept of a device assignment allows events to be associated with the asset they relate to.

A device assignment is an association between a device and (optionally) a related asset. Some assignments do not specify an asset and are referred to as unassociated. A real-world example of this is a vending machine that has wireless connectivity to report inventory. The device is the asset, so there is no need to associate an external asset.

Add Data to Device Assignment Data Stream

Adds data to an existing device assignment data stream. Note that the payload is the data to be stored and is in the format of raw binary data.

Request URI

POST/sitewhere/api/assignments/{token}/streams/{streamId:.+}

Path Parameters

Name	Description
streamId	Stream Id
token	Assignment token

Request Parameters

Name	Description	Required
sequenceNumber	Sequence Number	false

Create a New Device Assignment

This method creates a new device assignment.

Request URI

POST/sitewhere/api/assignments/

An unassociated assignment can be created by setting the assignment type to Unassociated as shown below:

{
  "token" : "910dc9b1-8df1-4464-9ee2-14981c6801c3",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Unassociated",
  "metadata" : {
    "renewable" : "true",
    "validUntil" : "2016-10-10"
  }
}Request

An associated assignment can be created by setting the assignment type to Associated and including the asset module and id.

{
  "token" : "9c6f524b-9831-48e5-894e-cfea0245b356",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "metadata" : {
    "renewable" : "true",
    "validUntil" : "2016-10-10"
  }
}Request

The result of the assignment create request is an assignment record including nested information about the device, site, and associated asset.

{
  "createdDate" : "2016-12-10T13:11:45.114-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "assetName" : "Derek Adams",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "site" : {
    "createdDate" : "2016-12-10T13:11:45.106-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "description" : "Construction site that contains many heavy equipment assets",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  },
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "status" : "Active",
  "activeDate" : "2016-12-10T13:11:45.114-0500",
  "device" : {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  },
  "associatedPerson" : {
    "id" : "derek",
    "name" : "Derek Adams",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "properties" : {
      "phone.number" : "777-555-1212"
    },
    "userName" : "dadams",
    "emailAddress" : "dadams@demoserver.com",
    "roles" : [ "dev" ]
  },
  "metadata" : { }
}Response

Create Alert Event for Device Assignment

Creates a new alert event for a device assignment.

Request URI

POST/sitewhere/api/assignments/{token}/alerts

Path Parameters

Name	Description
token	Assignment token

{
  "eventDate" : "2016-12-10T13:11:46.213-0500",
  "updateState" : true,
  "source" : "Device",
  "level" : "Warning",
  "type" : "engine.overheat",
  "message" : "Engine temperature is at top of operating range."
}Request

{
  "id" : "239472398473",
  "eventType" : "Alert",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.120-0500",
  "receivedDate" : "2016-12-10T13:11:45.120-0500",
  "source" : "Device",
  "level" : "Warning",
  "type" : "engine.overheat",
  "message" : "Engine temperature is at top of operating range.",
  "metadata" : { }
}Response

Create Command Invocation Event for Assignment

Creates a new command invocation event for a device assignment.

Request URI

POST/sitewhere/api/assignments/{token}/invocations

Path Parameters

Name	Description
token	Assignment token

{
  "eventDate" : "2016-12-10T13:11:45.122-0500",
  "updateState" : false,
  "initiator" : "REST",
  "initiatorId" : "admin",
  "target" : "Assignment",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  }
}Request

{
  "id" : "239402938454",
  "eventType" : "CommandInvocation",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.122-0500",
  "receivedDate" : "2016-12-10T13:11:45.122-0500",
  "initiator" : "REST",
  "initiatorId" : "admin",
  "target" : "Assignment",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  },
  "metadata" : { }
}Response

Create Command Response Event for Assignment

Creates a new command response event for a device assignment.

Request URI

POST/sitewhere/api/assignments/{token}/responses

Path Parameters

Name	Description
token	Assignment token

If the response to the originating event is another event, the response event id can be recorded as shown below:

{
  "eventDate" : "2016-12-10T13:11:45.123-0500",
  "updateState" : false,
  "originatingEventId" : "239402938454",
  "responseEventId" : "239472398473"
}Request

If the response to an event is a simple message, the message can be recorded as shown below:

{
  "eventDate" : "2016-12-10T13:11:45.123-0500",
  "updateState" : false,
  "originatingEventId" : "239402938454",
  "response" : "Reporting interval set successfully."
}Request

{
  "id" : "287494894849",
  "eventType" : "CommandResponse",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.123-0500",
  "receivedDate" : "2016-12-10T13:11:45.123-0500",
  "originatingEventId" : "239402938454",
  "responseEventId" : "239472398473",
  "metadata" : { }
}Response

Create Data Stream for Device Assignment

Create a new stream that will store binary data for a device assignment.

Request URI

POST/sitewhere/api/assignments/{token}/streams

Path Parameters

Name	Description
token	Assignment token

{
  "streamId" : "video-stream-1",
  "contentType" : "video/mpeg"
}Request

{
  "createdDate" : "2016-12-10T13:11:45.123-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "streamId" : "video-stream-1",
  "contentType" : "video/mpeg",
  "metadata" : { }
}Response

Create Location Event for Device Assignment

Creates a new location event for a device assignment.

Request URI

POST/sitewhere/api/assignments/{token}/locations

Path Parameters

Name	Description
token	Assignment token

{
  "eventDate" : "2016-12-10T13:11:46.176-0500",
  "updateState" : true,
  "latitude" : 34.103270338359664,
  "longitude" : -84.23874458667342,
  "elevation" : 0.0
}Request

{
  "id" : "203948023656",
  "eventType" : "Location",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.117-0500",
  "receivedDate" : "2016-12-10T13:11:45.117-0500",
  "latitude" : 34.103270338359664,
  "longitude" : -84.23874458667342,
  "elevation" : 0.0,
  "metadata" : { }
}Response

Create Measurements Event for Device Assignment

Creates a new measurements event for a device assignment.

Request URI

POST/sitewhere/api/assignments/{token}/measurements

Path Parameters

Name	Description
token	Assignment token

{
  "eventDate" : "2016-12-10T13:11:46.251-0500",
  "updateState" : true,
  "measurements" : {
    "engine.temperature" : 86.21,
    "fuel.level" : 32.68
  }
}Request

{
  "id" : "234203504574",
  "eventType" : "Measurements",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.119-0500",
  "receivedDate" : "2016-12-10T13:11:45.119-0500",
  "measurements" : {
    "engine.temperature" : 86.21,
    "fuel.level" : 32.68
  },
  "measurementsSummary" : "engine.temperature: 86.21, fuel.level: 32.68",
  "metadata" : { }
}Response

Delete an Existing Device Assignment

Delete an existing device assignment.

Request URI

DELETE/sitewhere/api/assignments/{token}

Path Parameters

Name	Description
token	Assignment token

Delete Policies Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.114-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "assetName" : "Derek Adams",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "site" : {
    "createdDate" : "2016-12-10T13:11:45.106-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "description" : "Construction site that contains many heavy equipment assets",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  },
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "status" : "Active",
  "activeDate" : "2016-12-10T13:11:45.114-0500",
  "device" : {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  },
  "associatedPerson" : {
    "id" : "derek",
    "name" : "Derek Adams",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "properties" : {
      "phone.number" : "777-555-1212"
    },
    "userName" : "dadams",
    "emailAddress" : "dadams@demoserver.com",
    "roles" : [ "dev" ]
  },
  "metadata" : { }
}Response

Get All Data from Device Assignment Data Stream

Gets all data from an existing device assignment data stream. Loops through all data chunks in order of sequence number and writes them as raw binary data on the response. Content type of the response data is set based on the content type assigned for the data stream.

Request URI

GET/sitewhere/api/assignments/{token}/streams/{streamId:.+}/data

Path Parameters

Name	Description
streamId	Stream Id
token	Assignment token

Get Data from Device Assignment Data Stream

Get a chunk of data from an existing device assignment data stream based on the stream id and sequence number for the data chunk. The response is the raw binary data stored in the chunk.

Request URI

GET/sitewhere/api/assignments/{token}/streams/{streamId:.+}/data/{sequenceNumber}

Path Parameters

Name	Description
sequenceNumber	Sequence Number
streamId	Stream Id
token	Assignment token

Get Device Assignment By Token

Get an existing device assignment based on its unique token.

Request URI

GET/sitewhere/api/assignments/{token}

Path Parameters

Name	Description
token	Assignment token

{
  "createdDate" : "2016-12-10T13:11:45.114-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "assetName" : "Derek Adams",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "site" : {
    "createdDate" : "2016-12-10T13:11:45.106-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "description" : "Construction site that contains many heavy equipment assets",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  },
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "status" : "Active",
  "activeDate" : "2016-12-10T13:11:45.114-0500",
  "device" : {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  },
  "associatedPerson" : {
    "id" : "derek",
    "name" : "Derek Adams",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "properties" : {
      "phone.number" : "777-555-1212"
    },
    "userName" : "dadams",
    "emailAddress" : "dadams@demoserver.com",
    "roles" : [ "dev" ]
  },
  "metadata" : { }
}Response

Get Device Assignment Data Stream by Id

Get information about an existing data stream associated with a device assignment based on its unique stream id.

Request URI

GET/sitewhere/api/assignments/{token}/streams/{streamId:.+}

Path Parameters

Name	Description
streamId	Stream Id
token	Assignment token

{
  "createdDate" : "2016-12-10T13:11:45.123-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "streamId" : "video-stream-1",
  "contentType" : "video/mpeg",
  "metadata" : { }
}Response

List Alert Events for Device Assignment

List all alert events for a device assignment based on the given criteria.

Request URI

GET/sitewhere/api/assignments/{token}/alerts

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "239472398473",
    "eventType" : "Alert",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.120-0500",
    "receivedDate" : "2016-12-10T13:11:45.120-0500",
    "source" : "Device",
    "level" : "Warning",
    "type" : "engine.overheat",
    "message" : "Engine temperature is at top of operating range.",
    "metadata" : { }
  }, {
    "id" : "230493483398",
    "eventType" : "Alert",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.121-0500",
    "receivedDate" : "2016-12-10T13:11:45.121-0500",
    "source" : "Device",
    "level" : "Critical",
    "type" : "fuel.level",
    "message" : "Fuel level is critical.",
    "metadata" : { }
  } ]
}Response

List Assignment Measurements as Chart Series

Lists all measurements that meet the given criteria in a format compatible with most series-based charts. A list of measurement ids may be passed so that only those measurements will be returned.

Request URI

GET/sitewhere/api/assignments/{token}/measurements/series

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
measurementIds	Measurement Ids	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

[ {
  "measurementId" : "engine.temperature",
  "entries" : [ {
    "value" : 86.21,
    "measurementDate" : "2016-12-10T13:11:45.119-0500"
  }, {
    "value" : 84.26,
    "measurementDate" : "2016-12-10T13:11:45.119-0500"
  } ]
}, {
  "measurementId" : "fuel.level",
  "entries" : [ {
    "value" : 32.68,
    "measurementDate" : "2016-12-10T13:11:45.119-0500"
  }, {
    "value" : 33.78,
    "measurementDate" : "2016-12-10T13:11:45.119-0500"
  } ]
} ]Response

List Command Invocation Events for Assignment

List all command invocation events for a device assignment based on the given criteria.

Request URI

GET/sitewhere/api/assignments/{token}/invocations

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
includeCommand	Include command information	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "230983938938",
    "eventType" : "CommandInvocation",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.121-0500",
    "receivedDate" : "2016-12-10T13:11:45.121-0500",
    "initiator" : "REST",
    "initiatorId" : "admin",
    "target" : "Assignment",
    "commandToken" : "3c1c61a3-652f-407e-80e7-fcfb13c10624",
    "parameterValues" : {
      "verbose" : "true"
    },
    "metadata" : { }
  }, {
    "id" : "239402938454",
    "eventType" : "CommandInvocation",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.122-0500",
    "receivedDate" : "2016-12-10T13:11:45.122-0500",
    "initiator" : "REST",
    "initiatorId" : "admin",
    "target" : "Assignment",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "parameterValues" : {
      "reboot" : "true",
      "interval" : "60"
    },
    "metadata" : { }
  } ]
}Response

List Command Response Events for Assignment

List all command response events for a device assignment based on the given criteria.

Request URI

GET/sitewhere/api/assignments/{token}/responses

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "254449849440",
    "eventType" : "CommandResponse",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.122-0500",
    "receivedDate" : "2016-12-10T13:11:45.122-0500",
    "originatingEventId" : "230983938938",
    "response" : "Firmware 1.1.0 (1.1.0.201512310800)",
    "metadata" : { }
  }, {
    "id" : "287494894849",
    "eventType" : "CommandResponse",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.123-0500",
    "receivedDate" : "2016-12-10T13:11:45.123-0500",
    "originatingEventId" : "239402938454",
    "responseEventId" : "239472398473",
    "metadata" : { }
  } ]
}Response

List Data Streams for Device Assignment

List all data streams for a device assignment based on the given criteria.

Request URI

GET/sitewhere/api/assignments/{token}/streams

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.123-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "streamId" : "video-stream-1",
    "contentType" : "video/mpeg",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.123-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "streamId" : "video-stream-2",
    "contentType" : "video/mpeg",
    "metadata" : { }
  } ]
}Response

List Events for Device Assignment

List all events for a device assignment based on the given criteria.

Request URI

GET/sitewhere/api/assignments/{token}/events

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 3,
  "results" : [ {
    "id" : "203948023656",
    "eventType" : "Location",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.117-0500",
    "receivedDate" : "2016-12-10T13:11:45.117-0500",
    "latitude" : 34.103270338359664,
    "longitude" : -84.23874458667342,
    "elevation" : 0.0,
    "metadata" : { }
  }, {
    "id" : "234203504574",
    "eventType" : "Measurements",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.119-0500",
    "receivedDate" : "2016-12-10T13:11:45.119-0500",
    "measurements" : {
      "engine.temperature" : 86.21,
      "fuel.level" : 32.68
    },
    "measurementsSummary" : "engine.temperature: 86.21, fuel.level: 32.68",
    "metadata" : { }
  }, {
    "id" : "239472398473",
    "eventType" : "Alert",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.120-0500",
    "receivedDate" : "2016-12-10T13:11:45.120-0500",
    "source" : "Device",
    "level" : "Warning",
    "type" : "engine.overheat",
    "message" : "Engine temperature is at top of operating range.",
    "metadata" : { }
  } ]
}Response

List Location Events for Device Assignment

List all location events for a device assignment based on the given criteria.

Request URI

GET/sitewhere/api/assignments/{token}/locations

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "203948023656",
    "eventType" : "Location",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.117-0500",
    "receivedDate" : "2016-12-10T13:11:45.117-0500",
    "latitude" : 34.103270338359664,
    "longitude" : -84.23874458667342,
    "elevation" : 0.0,
    "metadata" : { }
  }, {
    "id" : "230984233904",
    "eventType" : "Location",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.117-0500",
    "receivedDate" : "2016-12-10T13:11:45.117-0500",
    "latitude" : 34.10345084984494,
    "longitude" : -84.23983484847486,
    "elevation" : 0.1,
    "metadata" : { }
  } ]
}Response

List Measurement Events for Device Assignment

List all measurement events for a device assignment based on the given criteria.

Request URI

GET/sitewhere/api/assignments/{token}/measurements

Path Parameters

Name	Description
token	Assignment token

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "234203504574",
    "eventType" : "Measurements",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.119-0500",
    "receivedDate" : "2016-12-10T13:11:45.119-0500",
    "measurements" : {
      "engine.temperature" : 86.21,
      "fuel.level" : 32.68
    },
    "measurementsSummary" : "engine.temperature: 86.21, fuel.level: 32.68",
    "metadata" : { }
  }, {
    "id" : "230948239489",
    "eventType" : "Measurements",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.119-0500",
    "receivedDate" : "2016-12-10T13:11:45.119-0500",
    "measurements" : {
      "engine.temperature" : 84.26,
      "fuel.level" : 33.78
    },
    "measurementsSummary" : "engine.temperature: 84.26, fuel.level: 33.78",
    "metadata" : { }
  } ]
}Response

Mark Device Assignment as Missing

Set the status of an active device assignment to missing.

Request URI

POST/sitewhere/api/assignments/{token}/missing

Path Parameters

Name	Description
token	Assignment token

{
  "createdDate" : "2016-12-10T13:11:46.371-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "assetName" : "Derek Adams",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "site" : {
    "createdDate" : "2016-12-10T13:11:45.106-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "description" : "Construction site that contains many heavy equipment assets",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  },
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "status" : "Missing",
  "activeDate" : "2016-12-10T13:11:46.371-0500",
  "device" : {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  },
  "associatedPerson" : {
    "id" : "derek",
    "name" : "Derek Adams",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "properties" : {
      "phone.number" : "777-555-1212"
    },
    "userName" : "dadams",
    "emailAddress" : "dadams@demoserver.com",
    "roles" : [ "dev" ]
  },
  "metadata" : { }
}Response

Release an Active Device Assignment

Set the status of an active device assignment to released. Once released, the device may be reassigned.

Request URI

POST/sitewhere/api/assignments/{token}/end

Path Parameters

Name	Description
token	Assignment token

{
  "createdDate" : "2016-12-10T13:11:46.343-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "assetName" : "Derek Adams",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "site" : {
    "createdDate" : "2016-12-10T13:11:45.106-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "description" : "Construction site that contains many heavy equipment assets",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  },
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "status" : "Released",
  "activeDate" : "2016-12-10T13:11:46.343-0500",
  "releasedDate" : "2016-12-10T13:11:46.343-0500",
  "device" : {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  },
  "associatedPerson" : {
    "id" : "derek",
    "name" : "Derek Adams",
    "type" : "Person",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "properties" : {
      "phone.number" : "777-555-1212"
    },
    "userName" : "dadams",
    "emailAddress" : "dadams@demoserver.com",
    "roles" : [ "dev" ]
  },
  "metadata" : { }
}Response

Schedule Command Invocation

Create a job that will invoke a command based on a schedule.

Request URI

POST/sitewhere/api/assignments/{token}/invocations/schedules/{scheduleToken}

Path Parameters

Name	Description
scheduleToken	Schedule token
token	Assignment token

{
  "eventDate" : "2016-12-10T13:11:45.122-0500",
  "updateState" : false,
  "initiator" : "REST",
  "initiatorId" : "admin",
  "target" : "Assignment",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  }
}Request

{
  "createdDate" : "2016-12-10T13:11:45.138-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "be35c0fa-4201-4f0f-8998-63291b034872",
  "scheduleToken" : "5e772533-9fd8-4daa-8da1-63aa6642cc30",
  "jobType" : "CommandInvocation",
  "jobConfiguration" : {
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "param_interval" : "60",
    "param_reboot" : "true"
  },
  "jobState" : "Active",
  "metadata" : { }
}Response

Update Device Assignment Metadata

Update the metadata for an existing device assignment. The new values will add to the existing metadata, overwriting if entries exist for the given keys.

Request URI

PUT/sitewhere/api/assignments/{token}/metadata

Path Parameters

Name	Description
token	Assignment token

{
  "metadata" : {
    "key1" : "value1",
    "key2" : "value2"
  }
}Request

Device Command Invocations

Most operations related to device command invocations are found in the device assignments service. The methods in this service provide targeted functionality such as listing invocation responses and providing summary information about an invocation.

Get Command Invocation by Unique Id

Get information about a device command invocation based on its unique id in the system.

Request URI

GET/sitewhere/api/invocations/{id}

Path Parameters

Name	Description
id	Unique id

{
  "id" : "239402938454",
  "eventType" : "CommandInvocation",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.122-0500",
  "receivedDate" : "2016-12-10T13:11:45.122-0500",
  "initiator" : "REST",
  "initiatorId" : "admin",
  "target" : "Assignment",
  "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "parameterValues" : {
    "reboot" : "true",
    "interval" : "60"
  },
  "metadata" : { }
}Response

Get Command Invocation Summary

Get a summary of information related to a device command invocation that blends data from the command, the invocation details, and the responses in a concise format.

Request URI

GET/sitewhere/api/invocations/{id}/summary

Path Parameters

Name	Description
id	Unique id

{
  "name" : "getFirmwareVersion",
  "namespace" : "http://mycompany.com/devices",
  "invocationDate" : "2016-12-10T13:11:45.121-0500",
  "parameters" : [ {
    "name" : "verbose",
    "type" : "Bool",
    "value" : "true",
    "required" : false
  } ],
  "responses" : [ {
    "description" : "Ack (\"Firmware 1.1.0 (1.1.0.201512310800)\")",
    "date" : "2016-12-10T13:11:45.122-0500"
  } ],
  "metadata" : { }
}Response

List Responses for Command Invocation

List all responses for a device command invocation.

Request URI

GET/sitewhere/api/invocations/{id}/responses

Path Parameters

Name	Description
id	Invocation id

{
  "numResults" : 1,
  "results" : [ {
    "id" : "254449849440",
    "eventType" : "CommandResponse",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.122-0500",
    "receivedDate" : "2016-12-10T13:11:45.122-0500",
    "originatingEventId" : "230983938938",
    "response" : "Firmware 1.1.0 (1.1.0.201512310800)",
    "metadata" : { }
  } ]
}Response

Device Commands

Device specification commands specify methods SiteWhere can use to interact with a given hardware configuration. A device specification command has a unique name, a namespace, and zero or more parameters. Commands are intended to work in much the same way as calling an RPC method in a programming language. The command name and a list of strongly-typed parameters are encoded and sent to the device which interprets them and executes the corresponding logic. Each parameter has a name (which must be unique within the command), a type, and a flag indicating whether it is required.

NOTE: These methods will be refactored into the device specifications REST service as of SiteWhere 1.3.0. All other methods related to device specification commands are already in that service.

Delete Device Command by Unique Token

Delete an existing device command based on its unique token. Returns the device command that was deleted.

Request URI

DELETE/sitewhere/api/commands/{token}

Path Parameters

Name	Description
token	Token

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.111-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "namespace" : "http://mycompany.com/devices",
  "name" : "setReportInterval",
  "description" : "Set the device reporting interval (in seconds).",
  "parameters" : [ {
    "name" : "interval",
    "type" : "Int32",
    "required" : true
  }, {
    "name" : "reboot",
    "type" : "Bool",
    "required" : false
  } ],
  "metadata" : { }
}Response

Get Device Command by Unique Token

Gets an existing device command by unique token.

Request URI

GET/sitewhere/api/commands/{token}

Path Parameters

Name	Description
token	Token

{
  "createdDate" : "2016-12-10T13:11:45.111-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "namespace" : "http://mycompany.com/devices",
  "name" : "setReportInterval",
  "description" : "Set the device reporting interval (in seconds).",
  "parameters" : [ {
    "name" : "interval",
    "type" : "Int32",
    "required" : true
  }, {
    "name" : "reboot",
    "type" : "Bool",
    "required" : false
  } ],
  "metadata" : { }
}Response

Update an Existing Device Command

Updates an existing device command with new information. The updated command name can not be the same as any existing command names. Only fields that should be updated need to be passed.

Request URI

PUT/sitewhere/api/commands/{token}

Path Parameters

Name	Description
token	Token

{
  "namespace" : "http://mycompany.com/devices",
  "name" : "setReportIntervalUpd",
  "description" : "Set the device reporting interval (in seconds) (updated).",
  "parameters" : [ {
    "name" : "interval",
    "type" : "Int32",
    "required" : false
  }, {
    "name" : "reboot",
    "type" : "Bool",
    "required" : false
  } ]
}Request

{
  "createdDate" : "2016-12-10T13:11:46.017-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "namespace" : "http://mycompany.com/devices",
  "name" : "setReportIntervalUpd",
  "description" : "Set the device reporting interval (in seconds) (updated).",
  "parameters" : [ {
    "name" : "interval",
    "type" : "Int32",
    "required" : false
  }, {
    "name" : "reboot",
    "type" : "Bool",
    "required" : false
  } ],
  "metadata" : { }
}Response

Device Groups

Device groups are used to create an association between related devices. A device can belong to any number of groups and there is no limit to the size of a group. Device groups can also contain other device groups. Each element (device or subgroup) in a device group can have zero or more roles assigned. This allows external applications to query a device group and get a list of devices that serve a given role or roles, then take actions such as issuing commands or updating metadata.

Add Elements to Device Group

Add one or more elements to an existing device group.

Request URI

PUT/sitewhere/api/devicegroups/{groupToken}/elements

Path Parameters

Name	Description
groupToken	Unique token that identifies device group

[ {
  "type" : "Group",
  "elementId" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
  "roles" : [ "region" ]
}, {
  "type" : "Group",
  "elementId" : "8e560981-f3a4-4f31-ada4-c72e69984179",
  "roles" : [ "region" ]
}, {
  "type" : "Device",
  "elementId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "roles" : [ "standalone" ]
} ]Request

{
  "numResults" : 3,
  "results" : [ {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 0,
    "type" : "Group",
    "elementId" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
    "roles" : [ "region" ]
  }, {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 1,
    "type" : "Group",
    "elementId" : "8e560981-f3a4-4f31-ada4-c72e69984179",
    "roles" : [ "region" ]
  }, {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 2,
    "type" : "Device",
    "elementId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "roles" : [ "standalone" ]
  } ]
}Response

Create New Device Group

Create a new device group. If no token is specified in the request, a unique token will be automatically generated.

Request URI

POST/sitewhere/api/devicegroups/

{
  "token" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
  "name" : "Southeast",
  "description" : "Devices in the southeast region.",
  "roles" : [ "region", "americas" ]
}Request

{
  "createdDate" : "2016-12-10T13:11:45.128-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
  "name" : "Southeast",
  "description" : "Devices in the southeast region.",
  "roles" : [ "region", "americas" ],
  "metadata" : { }
}Response

Delete Device Group by Unique Token

Delete an existing device group based on its unique token. Returns the device group that was deleted.

Request URI

DELETE/sitewhere/api/devicegroups/{groupToken}

Path Parameters

Name	Description
groupToken	Unique token that identifies device group

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.128-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
  "name" : "Southeast",
  "description" : "Devices in the southeast region.",
  "roles" : [ "region", "americas" ],
  "metadata" : { }
}Response

Delete Elements from Device Group

Delete elements from an existing device group.

Request URI

DELETE/sitewhere/api/devicegroups/{groupToken}/elements

Path Parameters

Name	Description
groupToken	Unique token that identifies device group

[ {
  "type" : "Group",
  "elementId" : "8e560981-f3a4-4f31-ada4-c72e69984179",
  "roles" : [ ]
} ]Request

{
  "numResults" : 2,
  "results" : [ {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 0,
    "type" : "Group",
    "elementId" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
    "roles" : [ "region" ]
  }, {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 2,
    "type" : "Device",
    "elementId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "roles" : [ "standalone" ]
  } ]
}Response

Get Device Group by Unique Token

Get an existing device group by unique token.

Request URI

GET/sitewhere/api/devicegroups/{groupToken}

Path Parameters

Name	Description
groupToken	Unique token that identifies group

{
  "createdDate" : "2016-12-10T13:11:45.128-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
  "name" : "Southeast",
  "description" : "Devices in the southeast region.",
  "roles" : [ "region", "americas" ],
  "metadata" : { }
}Response

List Device Groups that Match Criteria

List all device groups that match the given criteria. In addition to the standard paging criteria, a role name may be specified so that only groups that have the given role will be returned.

Request URI

GET/sitewhere/api/devicegroups/

Request Parameters

Name	Description	Required
includeDeleted	Include deleted	false
role	Role	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.128-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "token" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
    "name" : "Southeast",
    "description" : "Devices in the southeast region.",
    "roles" : [ "region", "americas" ],
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.128-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "token" : "8e560981-f3a4-4f31-ada4-c72e69984179",
    "name" : "Northeast",
    "description" : "Devices in the northeast region.",
    "roles" : [ "region", "americas" ],
    "metadata" : { }
  } ]
}Response

List Elements in a Device Group

Lists elements in a device group. Elements may include both nested groups and device references. If includeDetails is set to true, the detailed device or group information is included in the list rather than just the identifier.

Request URI

GET/sitewhere/api/devicegroups/{groupToken}/elements

Path Parameters

Name	Description
groupToken	Unique token that identifies device group

Request Parameters

Name	Description	Required
includeDetails	Include detailed element information	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 3,
  "results" : [ {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 0,
    "type" : "Group",
    "elementId" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
    "roles" : [ "region" ]
  }, {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 1,
    "type" : "Group",
    "elementId" : "8e560981-f3a4-4f31-ada4-c72e69984179",
    "roles" : [ "region" ]
  }, {
    "groupToken" : "38745f7f-b5c6-477a-8388-48844ee38862",
    "index" : 2,
    "type" : "Device",
    "elementId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "roles" : [ "standalone" ]
  } ]
}Response

Update an Existing Device Group

Update information in an existing device group. Only fields that should be changed need to be passed.

Request URI

PUT/sitewhere/api/devicegroups/{groupToken}

Path Parameters

Name	Description
groupToken	Unique token that identifies device group

{
  "name" : "Southeast Updated",
  "description" : "Devices in the southeast region. Updated."
}Request

{
  "createdDate" : "2016-12-10T13:11:45.890-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "24288cbd-e8aa-4b35-a6b3-27e24a123718",
  "name" : "Southeast Updated",
  "description" : "Devices in the southeast region. Updated.",
  "roles" : [ "region", "americas" ],
  "metadata" : { }
}Response

Device Specifications

Device specifications are used to capture characteristics of a given hardware configuration. This is not necessarily a one-to-one mapping to a part number or SKU since some peripheral devices may have been added or certain characteristics upgraded. A device specification contains a reference to a hardware asset which provides the basic information about the hardware including name, description, image URL, etc.

A device specification contains a list of commands that may be invoked by SiteWhere on the device. It is perfectly acceptable for two device specifications to point to the same asset type, but have a different set of commands, reflecting different configurations of the given device.

Create Device Command for Specification

Create a new device command for a device specification. If no token is passed in the request, a unique token will be generated automatically.

Request URI

POST/sitewhere/api/specifications/{token}/commands

Path Parameters

Name	Description
token	Token

{
  "token" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "namespace" : "http://mycompany.com/devices",
  "name" : "setReportInterval",
  "description" : "Set the device reporting interval (in seconds).",
  "parameters" : [ {
    "name" : "interval",
    "type" : "Int32",
    "required" : true
  }, {
    "name" : "reboot",
    "type" : "Bool",
    "required" : false
  } ]
}Request

{
  "createdDate" : "2016-12-10T13:11:45.111-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "namespace" : "http://mycompany.com/devices",
  "name" : "setReportInterval",
  "description" : "Set the device reporting interval (in seconds).",
  "parameters" : [ {
    "name" : "interval",
    "type" : "Int32",
    "required" : true
  }, {
    "name" : "reboot",
    "type" : "Bool",
    "required" : false
  } ],
  "metadata" : { }
}Response

Create New Device Specification

Create a new device specification. If no token is specified, a unique token will be created automatically.

Request URI

POST/sitewhere/api/specifications/

{
  "token" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "name" : "MeiTrack GPS",
  "assetModuleId" : "my-devices",
  "assetId" : "175",
  "containerPolicy" : "Standalone"
}Request

{
  "createdDate" : "2016-12-10T13:11:45.109-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "name" : "MeiTrack GPS",
  "assetModuleId" : "my-devices",
  "assetId" : "175",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
  "containerPolicy" : "Standalone",
  "metadata" : { }
}Response

Delete Existing Device Specification

Delete an existing device specification based on its unique token. Information about the specification that was deleted is returned in the response.

Request URI

DELETE/sitewhere/api/specifications/{token}

Path Parameters

Name	Description
token	Token

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.109-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "name" : "MeiTrack GPS",
  "assetModuleId" : "my-devices",
  "assetId" : "175",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
  "containerPolicy" : "Standalone",
  "metadata" : { }
}Response

Get Specification GPB by Unique Token

Get the device specification Google Protocol Buffers definition as plain text output.

Request URI

GET/sitewhere/api/specifications/{token}/proto

Path Parameters

Name	Description
token	Token

Get Specification GPB File by Unique Token

Get the device specification Google Protocol Buffers definition as a file. If a browser is pointed to the URL, it will offer to download and save the protobuf definition.

Request URI

GET/sitewhere/api/specifications/{token}/spec.proto

Path Parameters

Name	Description
token	Token

Get Specification by Unique Token

Get a device specifiation by unique token.

Request URI

GET/sitewhere/api/specifications/{token}

Path Parameters

Name	Description
token	Token

Request Parameters

Name	Description	Required
includeAsset	Include detailed asset information	false

{
  "createdDate" : "2016-12-10T13:11:45.109-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "name" : "MeiTrack GPS",
  "assetModuleId" : "my-devices",
  "assetId" : "175",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
  "containerPolicy" : "Standalone",
  "metadata" : { }
}Response

List Device Commands by Namespace

List device commands for a specification and group them by namespaces.

Request URI

GET/sitewhere/api/specifications/{token}/namespaces

Path Parameters

Name	Description
token	Token

Request Parameters

Name	Description	Required
includeDeleted	Include deleted	false

{
  "numResults" : 1,
  "results" : [ {
    "value" : "http://mycompany.com/devices",
    "commands" : [ {
      "createdDate" : "2016-12-10T13:11:45.110-0500",
      "createdBy" : "admin",
      "updatedDate" : null,
      "updatedBy" : null,
      "deleted" : false,
      "token" : "3c1c61a3-652f-407e-80e7-fcfb13c10624",
      "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
      "namespace" : "http://mycompany.com/devices",
      "name" : "getFirmwareVersion",
      "description" : "Get version of device firmware.",
      "parameters" : [ {
        "name" : "verbose",
        "type" : "Bool",
        "required" : false
      } ],
      "metadata" : { }
    }, {
      "createdDate" : "2016-12-10T13:11:45.111-0500",
      "createdBy" : "admin",
      "updatedDate" : null,
      "updatedBy" : null,
      "deleted" : false,
      "token" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
      "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
      "namespace" : "http://mycompany.com/devices",
      "name" : "setReportInterval",
      "description" : "Set the device reporting interval (in seconds).",
      "parameters" : [ {
        "name" : "interval",
        "type" : "Int32",
        "required" : true
      }, {
        "name" : "reboot",
        "type" : "Bool",
        "required" : false
      } ],
      "metadata" : { }
    } ]
  } ]
}Response

List Device Commands for Specification

List device commands for a specification that meet the given criteria.

Request URI

GET/sitewhere/api/specifications/{token}/commands

Path Parameters

Name	Description
token	Token

Request Parameters

Name	Description	Required
includeDeleted	Include deleted	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.110-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "token" : "3c1c61a3-652f-407e-80e7-fcfb13c10624",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "namespace" : "http://mycompany.com/devices",
    "name" : "getFirmwareVersion",
    "description" : "Get version of device firmware.",
    "parameters" : [ {
      "name" : "verbose",
      "type" : "Bool",
      "required" : false
    } ],
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.111-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "token" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "namespace" : "http://mycompany.com/devices",
    "name" : "setReportInterval",
    "description" : "Set the device reporting interval (in seconds).",
    "parameters" : [ {
      "name" : "interval",
      "type" : "Int32",
      "required" : true
    }, {
      "name" : "reboot",
      "type" : "Bool",
      "required" : false
    } ],
    "metadata" : { }
  } ]
}Response

List Specifications that Match Criteria

List device specifictions that meet the given criteria.

Request URI

GET/sitewhere/api/specifications/

Request Parameters

Name	Description	Required
includeAsset	Include detailed asset information	false
includeDeleted	Include deleted	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.109-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "name" : "MeiTrack GPS",
    "assetModuleId" : "my-devices",
    "assetId" : "175",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "containerPolicy" : "Standalone",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "2f540b66-b6ab-4fbe-bdf3-ca6aaf103848",
    "name" : "Heart Monitor",
    "assetModuleId" : "ac-persons",
    "assetId" : "303",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/health/heartmonitor.jpg",
    "containerPolicy" : "Standalone",
    "metadata" : { }
  } ]
}Response

Update Existing Device Specification

Updates an existing device speicification. Only fields that should be updated need to be included.

Request URI

PUT/sitewhere/api/specifications/{token}

Path Parameters

Name	Description
token	Token

{
  "name" : "MeiTrack GPS Updated."
}Request

{
  "createdDate" : "2016-12-10T13:11:45.482-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "name" : "MeiTrack GPS Updated.",
  "assetModuleId" : "my-devices",
  "assetId" : "175",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
  "containerPolicy" : "Standalone",
  "metadata" : { }
}Response

Devices

Devices are a representation of connected physical hardware that conforms to a known device specification. Each device is addressable by a hardware id that identifies it uniquely in the system.

Add Multiple Events for Device

Add multiple events for a device. Many measurements, locations, and alerts can be added for a device in a single call. The response contains information about the events that were created.

Request URI

POST/sitewhere/api/devices/{hardwareId}/batch

Path Parameters

Name	Description
hardwareId	Hardware id

{
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "measurements" : [ {
    "eventDate" : "2016-12-10T13:11:45.765-0500",
    "updateState" : true,
    "measurements" : {
      "engine.temperature" : 86.21,
      "fuel.level" : 32.68
    }
  } ],
  "locations" : [ {
    "eventDate" : "2016-12-10T13:11:45.765-0500",
    "updateState" : true,
    "latitude" : 34.103270338359664,
    "longitude" : -84.23874458667342,
    "elevation" : 0.0
  } ],
  "alerts" : [ {
    "eventDate" : "2016-12-10T13:11:45.765-0500",
    "updateState" : true,
    "source" : "Device",
    "level" : "Warning",
    "type" : "engine.overheat",
    "message" : "Engine temperature is at top of operating range."
  } ]
}Request

{
  "createdMeasurements" : [ {
    "id" : "234203504574",
    "eventType" : "Measurements",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.119-0500",
    "receivedDate" : "2016-12-10T13:11:45.119-0500",
    "measurements" : {
      "engine.temperature" : 86.21,
      "fuel.level" : 32.68
    },
    "measurementsSummary" : "engine.temperature: 86.21, fuel.level: 32.68",
    "metadata" : { }
  } ],
  "createdLocations" : [ {
    "id" : "203948023656",
    "eventType" : "Location",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.117-0500",
    "receivedDate" : "2016-12-10T13:11:45.117-0500",
    "latitude" : 34.103270338359664,
    "longitude" : -84.23874458667342,
    "elevation" : 0.0,
    "metadata" : { }
  } ],
  "createdAlerts" : [ {
    "id" : "239472398473",
    "eventType" : "Alert",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.120-0500",
    "receivedDate" : "2016-12-10T13:11:45.120-0500",
    "source" : "Device",
    "level" : "Warning",
    "type" : "engine.overheat",
    "message" : "Engine temperature is at top of operating range.",
    "metadata" : { }
  } ]
}Response

Create New Device

Create a new device. The hardware id of the new device must be unique in the system.

Request URI

POST/sitewhere/api/devices/

{
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "comments" : "Equipment tracker."
}Request

{
  "createdDate" : "2016-12-10T13:11:45.112-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "deviceElementMappings" : [ ],
  "comments" : "Equipment tracker.",
  "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "metadata" : { }
}Response

Create New Device Element Mapping

Add a new mapping of a path within the device element schema to the hardware id of a child device attached to that path. This method has the side effect of setting up the reverse relationship with the parent id of the contained device pointing back to the container device.

This method only applies to devices that use a composite specification.

Request URI

POST/sitewhere/api/devices/{hardwareId}/mappings

Path Parameters

Name	Description
hardwareId	Hardware id

{
  "deviceElementSchemaPath" : "/sensors/vitals",
  "hardwareId" : "bfca26f1-2b33-449c-8335-78ff5852e326"
}Request

{
  "createdDate" : "2016-12-10T13:11:45.803-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "deviceElementMappings" : [ {
    "deviceElementSchemaPath" : "/sensors/vitals",
    "hardwareId" : "bfca26f1-2b33-449c-8335-78ff5852e326"
  } ],
  "comments" : "Equipment tracker.",
  "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "metadata" : { }
}Response

Delete Device Based on Unique Hardware Id

Delete a device based on its unique hardware id. Returns information about the device that was deleted.

Request URI

DELETE/sitewhere/api/devices/{hardwareId}

Path Parameters

Name	Description
hardwareId	Hardware id

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.112-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "deviceElementMappings" : [ ],
  "comments" : "Equipment tracker.",
  "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "metadata" : { }
}Response

Delete Existing Device Element Mapping

Delete an existing device element mapping based on the relative path in the device element schema to which the nested device is mapped.

This method only applies to devices that use a composite specification.

Request URI

DELETE/sitewhere/api/devices/{hardwareId}/mappings

Path Parameters

Name	Description
hardwareId	Hardware id

Request Parameters

Name	Description	Required
path	Device element path	true

{
  "createdDate" : "2016-12-10T13:11:45.112-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "deviceElementMappings" : [ ],
  "comments" : "Equipment tracker.",
  "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assetId" : "175",
  "assetName" : "MeiTrack MT90",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
  "metadata" : { }
}Response

Get Current Assignment for Device

Get information about the current assignment for a device. The includeXXX parameters allow the level of detail to be controlled.

Request URI

GET/sitewhere/api/devices/{hardwareId}/assignment

Path Parameters

Name	Description
hardwareId	Hardware id

Request Parameters

Name	Description	Required
includeAsset	Include detailed asset information	false
includeDevice	Include detailed device information	false
includeSite	Include detailed site information	false

{
  "createdDate" : "2016-12-10T13:11:45.114-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "assetName" : "Derek Adams",
  "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "status" : "Active",
  "activeDate" : "2016-12-10T13:11:45.114-0500",
  "metadata" : { }
}Response

Get Device by Unique Hardware Id

Get a device by its unique hardware id. This method includes a number of includeXXX flags that indicate whether related data such as the device specification and current assignment information should be included with the device data.

Request URI

GET/sitewhere/api/devices/{hardwareId}

Path Parameters

Name	Description
hardwareId	Hardware id

Request Parameters

Name	Description	Required
includeAsset	Include detailed asset information	false
includeAssignment	Include assignment if associated	false
includeNested	Include detailed nested device information	false
includeSite	Include site information	false
includeSpecification	Include specification information	false

{
  "createdDate" : "2016-12-10T13:11:45.112-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceElementMappings" : [ ],
  "comments" : "Equipment tracker.",
  "specification" : {
    "createdDate" : "2016-12-10T13:11:45.109-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "name" : "MeiTrack GPS",
    "assetModuleId" : "my-devices",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "asset" : {
      "id" : "175",
      "name" : "MeiTrack MT90",
      "type" : "Device",
      "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
      "properties" : {
        "sos.button" : "true",
        "weight" : "1.000",
        "manufacturer" : "MeiTrack"
      },
      "sku" : "MT90",
      "description" : "MT90 is a waterproof GPS personal tracker suitable for lone workers, kids, aged, pet, assets, vehicle and fleet management."
    },
    "containerPolicy" : "Standalone",
    "metadata" : { }
  },
  "assignment" : {
    "createdDate" : "2016-12-10T13:11:45.114-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "assetName" : "Derek Adams",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "status" : "Active",
    "activeDate" : "2016-12-10T13:11:45.114-0500",
    "metadata" : { }
  },
  "site" : {
    "createdDate" : "2016-12-10T13:11:45.106-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "description" : "Construction site that contains many heavy equipment assets",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  },
  "metadata" : { }
}Response

List Assignment History for Device

Get the history of assignments for a device in reverse chronological order.

Request URI

GET/sitewhere/api/devices/{hardwareId}/assignments

Path Parameters

Name	Description
hardwareId	Hardware id

Request Parameters

Name	Description	Required
includeAsset	Include detailed asset information	false
includeDevice	Include detailed device information	false
includeSite	Include detailed site information	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.114-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "assetName" : "Derek Adams",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/derek.jpg",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "status" : "Active",
    "activeDate" : "2016-12-10T13:11:45.114-0500",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.115-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "b91b8f1a-7040-475a-bf05-275418b335d8",
    "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "martin",
    "assetName" : "Martin Weber",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/people/martin.jpg",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "status" : "Released",
    "activeDate" : "2016-12-10T13:11:45.115-0500",
    "releasedDate" : "2016-12-10T13:11:45.115-0500",
    "metadata" : { }
  } ]
}Response

List Devices id Device Group

List devices in a device group that also match the other criteria.

Request URI

GET/sitewhere/api/devices/group/{groupToken}

Path Parameters

Name	Description
groupToken	Group token

Request Parameters

Name	Description	Required
endDate	End date	false
excludeAssigned	Exclude assigned devices	false
includeAssignment	Include assignment information if associated	false
includeDeleted	Include deleted devices	false
includeSpecification	Include specification information	false
site	Site filter	false
specification	Specification filter	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.113-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "02efd10-da41-4b06-81fe-d478188daf0e",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker 2.",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  } ]
}Response

List Devices in Device Groups with Role

List devices in groups assigned a given role and matching the other criteria.

Request URI

GET/sitewhere/api/devices/grouprole/{role}

Path Parameters

Name	Description
role	Group role

Request Parameters

Name	Description	Required
endDate	End date	false
excludeAssigned	Exclude assigned devices	false
includeAssignment	Include assignment information if associated	false
includeDeleted	Include deleted devices	false
includeSpecification	Include specification information	false
site	Site filter	false
specification	Specification filter	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.113-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "02efd10-da41-4b06-81fe-d478188daf0e",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker 2.",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  } ]
}Response

List Devices that Match Criteria

List all devices that match the given criteria. The includeXXX parameters may be used to include extra information about the matching devices.

Request URI

GET/sitewhere/api/devices/

Request Parameters

Name	Description	Required
endDate	End date	false
excludeAssigned	Exclude assigned devices	false
includeAssignment	Include assignment information if associated	false
includeDeleted	Include deleted devices	false
includeSpecification	Include specification information	false
site	Site filter	false
specification	Specification filter	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.113-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "bfca26f1-2b33-449c-8335-78ff5852e326",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "2f540b66-b6ab-4fbe-bdf3-ca6aaf103848",
    "deviceElementMappings" : [ ],
    "comments" : "Tracks vital statistics including heart rate.",
    "assetId" : "303",
    "assetName" : "Caterpillar 320E L Excavator",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/cat/cat-320e.jpg",
    "metadata" : { }
  } ]
}Response

List Devices Using a Given Specification

List all devices that use a given specification and match the other criteria.

Request URI

GET/sitewhere/api/devices/specification/{token}

Path Parameters

Name	Description
token	Specification token

Request Parameters

Name	Description	Required
endDate	End date	false
excludeAssigned	Exclude assigned devices	false
includeAssignment	Include assignment information if associated	false
includeDeleted	Include deleted devices	false
includeSpecification	Include specification information	false
site	Site filter	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.112-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker.",
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.113-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "hardwareId" : "02efd10-da41-4b06-81fe-d478188daf0e",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
    "deviceElementMappings" : [ ],
    "comments" : "Equipment tracker 2.",
    "assetId" : "175",
    "assetName" : "MeiTrack MT90",
    "assetImageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/meitrack/mt90.jpg",
    "metadata" : { }
  } ]
}Response

Update an Existing Device

Updates information about an existing device. The hardware id for a device can not be updated since there may be external references to it. The site for a device can not be updated if the device has an active assignment.

Request URI

PUT/sitewhere/api/devices/{hardwareId}

Path Parameters

Name	Description
hardwareId	Hardware id

{
  "comments" : "Equipment tracker. Updated."
}Request

{
  "createdDate" : "2016-12-10T13:11:45.720-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "hardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "specificationToken" : "82043707-9e3d-441f-bdcc-33cf0f4f7260",
  "deviceElementMappings" : [ ],
  "comments" : "Equipment tracker. Updated.",
  "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "metadata" : { }
}Response

Events

The events service is used to directly access event information by unique event id. All other event-related methods are available in the device assignments service since events are always posted in the context of an assignment.

Get Event by Unique Id

Get an event based on its unique identifier in the system. This is used to directly reference an event independently of the containing assignment. For instance, responses are tied back to originating events based on event id without any reference to the assignment.

Request URI

GET/sitewhere/api/events/{eventId}

Path Parameters

Name	Description
eventId	Event id

If the result is a measurements event, the response will be similar to the one below:

{
  "id" : "234203504574",
  "eventType" : "Measurements",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.119-0500",
  "receivedDate" : "2016-12-10T13:11:45.119-0500",
  "measurements" : {
    "engine.temperature" : 86.21,
    "fuel.level" : 32.68
  },
  "measurementsSummary" : "engine.temperature: 86.21, fuel.level: 32.68",
  "metadata" : { }
}Response

If the result is a location event, the response will be similar to the one below:

{
  "id" : "203948023656",
  "eventType" : "Location",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.117-0500",
  "receivedDate" : "2016-12-10T13:11:45.117-0500",
  "latitude" : 34.103270338359664,
  "longitude" : -84.23874458667342,
  "elevation" : 0.0,
  "metadata" : { }
}Response

If the result is an alert event, the response will be similar to the one below:

{
  "id" : "239472398473",
  "eventType" : "Alert",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.120-0500",
  "receivedDate" : "2016-12-10T13:11:45.120-0500",
  "source" : "Device",
  "level" : "Warning",
  "type" : "engine.overheat",
  "message" : "Engine temperature is at top of operating range.",
  "metadata" : { }
}Response

External Search Providers

SiteWhere supports an abstracted view of external search engines that operate on SiteWhere data. External search providers allow the SiteWhere REST services to take advantage of features particular to the underlying search engine while still returning results in a predictable format. For instance, the Solr external search provider allows a user to pass a Solr query string as part of the REST call, taking advantage of powerful Solr features while returning a result set in the same format SiteWhere uses for searches on its core datastores. This approach allows SiteWhere to enrich the result data if necessary, and presents a single view of the data whether stored in SiteWhere or indexed in an engine optimized for adhoc queries.

List Available Search Providers

Get list of available external search providers.

Request URI

GET/sitewhere/api/search/

{
  "numResults" : 1,
  "results" : [ {
    "id" : "solr",
    "name" : "Apache Solr"
  } ]
}Response

Search for Events in Provider

Query an external search provider for events matching criteria. The criteria is passed in the form of the query string passed to the method. Interpretation of the criteria is up to the search provider.

Request URI

GET/sitewhere/api/search/{providerId}/events

Path Parameters

Name	Description
providerId	Search provider id

[ {
  "id" : "203948023656",
  "eventType" : "Location",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.117-0500",
  "receivedDate" : "2016-12-10T13:11:45.117-0500",
  "latitude" : 34.103270338359664,
  "longitude" : -84.23874458667342,
  "elevation" : 0.0,
  "metadata" : { }
}, {
  "id" : "234203504574",
  "eventType" : "Measurements",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.119-0500",
  "receivedDate" : "2016-12-10T13:11:45.119-0500",
  "measurements" : {
    "engine.temperature" : 86.21,
    "fuel.level" : 32.68
  },
  "measurementsSummary" : "engine.temperature: 86.21, fuel.level: 32.68",
  "metadata" : { }
}, {
  "id" : "239472398473",
  "eventType" : "Alert",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
  "assignmentType" : "Associated",
  "assetModuleId" : "ac-persons",
  "assetId" : "derek",
  "eventDate" : "2016-12-10T13:11:45.120-0500",
  "receivedDate" : "2016-12-10T13:11:45.120-0500",
  "source" : "Device",
  "level" : "Warning",
  "type" : "engine.overheat",
  "message" : "Engine temperature is at top of operating range.",
  "metadata" : { }
} ]Response

Granted Authorities

Granted authorities are permissions assigned to users to allow access to various pieces of system functionality. When creating a user, a list of granted authorities are chosen based on their expected needs in the system.

Granted authorities are used to restrict access to the REST services. Each REST call must include basic authentication information associated with a system user. Based on the authorities associated with the user, certain REST methods may or may not be available.

Create a New Authority

Create a new granted authority that will be available for assignment to users.

Request URI

POST/sitewhere/api/authorities/

{
  "authority" : "REST",
  "description" : "REST services access",
  "parent" : null,
  "group" : false
}Request

{
  "authority" : "REST",
  "description" : "REST services access",
  "parent" : "GRP_ACCESS",
  "group" : false
}Response

Get Authority by Id

Get an authority by its unique identifier.

Request URI

GET/sitewhere/api/authorities/{name}

Path Parameters

Name	Description
name	Authority name

{
  "authority" : "REST",
  "description" : "REST services access",
  "parent" : "GRP_ACCESS",
  "group" : false
}Response

List Authorities that Match Criteria

List all granted authorities that match the given criteria.

Request URI

GET/sitewhere/api/authorities/

Request Parameters

Name	Description	Required
count	Max records to return	false

[ {
  "authority" : "REST",
  "description" : "REST services access",
  "parent" : "GRP_ACCESS",
  "group" : false
}, {
  "authority" : "ADMINISTER_USERS",
  "description" : "Administer all users",
  "parent" : "GRP_USERS",
  "group" : false
} ]Response

Scheduled Jobs

Scheduled jobs are system actions that are performed on a specified schedule. Current jobs that may be scheduled include simple command invocations and batch command invocations. Other system scheduled system actions will be added in the future.

Create New Scheduled Job

Create a new scheduled job. If no token is provided one will be generated automatically.

Request URI

POST/sitewhere/api/jobs/

{
  "token" : "be35c0fa-4201-4f0f-8998-63291b034872",
  "scheduleToken" : "5e772533-9fd8-4daa-8da1-63aa6642cc30",
  "jobType" : "CommandInvocation",
  "jobConfiguration" : {
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "param_interval" : "60",
    "param_reboot" : "true"
  }
}Request

{
  "createdDate" : "2016-12-10T13:11:45.138-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "be35c0fa-4201-4f0f-8998-63291b034872",
  "scheduleToken" : "5e772533-9fd8-4daa-8da1-63aa6642cc30",
  "jobType" : "CommandInvocation",
  "jobConfiguration" : {
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "param_interval" : "60",
    "param_reboot" : "true"
  },
  "jobState" : "Active",
  "metadata" : { }
}Response

Delete Scheduled Job

Delete an existing scheduled job. Returns information about the job that was deleted.

Request URI

DELETE/sitewhere/api/jobs/{token}

Path Parameters

Name	Description
token	Token

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.138-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "be35c0fa-4201-4f0f-8998-63291b034872",
  "scheduleToken" : "5e772533-9fd8-4daa-8da1-63aa6642cc30",
  "jobType" : "CommandInvocation",
  "jobConfiguration" : {
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "param_interval" : "60",
    "param_reboot" : "true"
  },
  "jobState" : "Active",
  "metadata" : { }
}Response

Get Scheduled Job by Token

Get information about a scheduled job based on its unique token.

Request URI

GET/sitewhere/api/jobs/{token}

Path Parameters

Name	Description
token	Token

{
  "createdDate" : "2016-12-10T13:11:45.138-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "be35c0fa-4201-4f0f-8998-63291b034872",
  "scheduleToken" : "5e772533-9fd8-4daa-8da1-63aa6642cc30",
  "jobType" : "CommandInvocation",
  "jobConfiguration" : {
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "param_interval" : "60",
    "param_reboot" : "true"
  },
  "jobState" : "Active",
  "metadata" : { }
}Response

List Scheduled Jobs Matching Criteria

List all scheduled jobs matching the given criteria.

Request URI

GET/sitewhere/api/jobs/

Request Parameters

Name	Description	Required
includeContext	Include context information	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.138-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "be35c0fa-4201-4f0f-8998-63291b034872",
    "scheduleToken" : "5e772533-9fd8-4daa-8da1-63aa6642cc30",
    "jobType" : "CommandInvocation",
    "jobConfiguration" : {
      "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
      "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
      "param_interval" : "60",
      "param_reboot" : "true"
    },
    "jobState" : "Active",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.138-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "2fbb6229-4ca1-42d4-bdd7-49f09c757399",
    "scheduleToken" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
    "jobType" : "CommandInvocation",
    "jobConfiguration" : {
      "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
      "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
      "param_interval" : "60",
      "param_reboot" : "true"
    },
    "jobState" : "Active",
    "metadata" : { }
  } ]
}Response

Update Existing Scheduled Job

Updates an existing scheduled job with new information. Only the updated fields need to be passed.

Request URI

PUT/sitewhere/api/jobs/{token}

Path Parameters

Name	Description
token	Token

{
  "scheduleToken" : "95ff6a81-3d92-4b10-b8af-957c172ad97b"
}Request

{
  "createdDate" : "2016-12-10T13:11:45.634-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "be35c0fa-4201-4f0f-8998-63291b034872",
  "scheduleToken" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
  "jobType" : "CommandInvocation",
  "jobConfiguration" : {
    "assignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "param_interval" : "60",
    "param_reboot" : "true"
  },
  "jobState" : "Active",
  "metadata" : { }
}Response

Schedules

Schedules provide the ability to run jobs at another point in time rather than immediately firing an action. All schedules may be bounded by a start and end time during which the firing of the job is controlled by other scheduling criteria. Simple scheduling allows for a job to be fired at an interval and repeated for a given number of times (or repeated infinitely if desired). Alternatively, jobs may be specified as cron expressions that indicate a specific schedule on which they run (e.g. every Monday, Wednesday, and Friday at 2pm and 8pm except for holidays).

Create a New Schedule

Creates a new schedule. If no token is provided, one will be created automatically.

Request URI

POST/sitewhere/api/schedules/

{
  "token" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
  "name" : "Every thirty seconds",
  "triggerType" : "SimpleTrigger",
  "triggerConfiguration" : {
    "repeatInterval" : "30000",
    "repeatCount" : "0"
  },
  "startDate" : 1481393505135,
  "endDate" : 1481393505135
}Request

{
  "createdDate" : "2016-12-10T13:11:45.136-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
  "name" : "Every thirty seconds",
  "triggerType" : "SimpleTrigger",
  "triggerConfiguration" : {
    "repeatInterval" : "30000",
    "repeatCount" : "0"
  },
  "startDate" : "2016-12-10T13:11:45.135-0500",
  "endDate" : "2016-12-10T13:11:45.135-0500",
  "metadata" : { }
}Response

Delete a Schedule

Delete an existing schedule. Returns information about the schedule that was deleted.

Request URI

DELETE/sitewhere/api/schedules/{token}

Path Parameters

Name	Description
token	Token

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.136-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
  "name" : "Every thirty seconds",
  "triggerType" : "SimpleTrigger",
  "triggerConfiguration" : {
    "repeatInterval" : "30000",
    "repeatCount" : "0"
  },
  "startDate" : "2016-12-10T13:11:45.135-0500",
  "endDate" : "2016-12-10T13:11:45.135-0500",
  "metadata" : { }
}Response

Get Schedule by Token

Get an existing schedule by unique token.

Request URI

GET/sitewhere/api/schedules/{token}

Path Parameters

Name	Description
token	Token

{
  "createdDate" : "2016-12-10T13:11:45.136-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
  "name" : "Every thirty seconds",
  "triggerType" : "SimpleTrigger",
  "triggerConfiguration" : {
    "repeatInterval" : "30000",
    "repeatCount" : "0"
  },
  "startDate" : "2016-12-10T13:11:45.135-0500",
  "endDate" : "2016-12-10T13:11:45.135-0500",
  "metadata" : { }
}Response

List Schedules that Match Criteria

List all schedules that match the given criteria.

Request URI

GET/sitewhere/api/schedules/

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.136-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "token" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
    "name" : "Every thirty seconds",
    "triggerType" : "SimpleTrigger",
    "triggerConfiguration" : {
      "repeatInterval" : "30000",
      "repeatCount" : "0"
    },
    "startDate" : "2016-12-10T13:11:45.135-0500",
    "endDate" : "2016-12-10T13:11:45.135-0500",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.136-0500",
    "createdBy" : "admin",
    "updatedDate" : null,
    "updatedBy" : null,
    "deleted" : false,
    "token" : "5e772533-9fd8-4daa-8da1-63aa6642cc30",
    "name" : "On the hour",
    "triggerType" : "CronTrigger",
    "triggerConfiguration" : {
      "cronExpression" : "0 0 0/1 1/1 * ? *"
    },
    "startDate" : "2016-12-10T13:11:45.136-0500",
    "endDate" : "2016-12-10T13:11:45.136-0500",
    "metadata" : { }
  } ]
}Response

Update an Existing Schedule

Update information in an existing schedule. Only fields that are to be changed need to be provided.

Request URI

PUT/sitewhere/api/schedules/{token}

Path Parameters

Name	Description
token	Token

{
  "name" : "Every thirty seconds Updated"
}Request

{
  "createdDate" : "2016-12-10T13:11:45.666-0500",
  "createdBy" : "admin",
  "updatedDate" : null,
  "updatedBy" : null,
  "deleted" : false,
  "token" : "95ff6a81-3d92-4b10-b8af-957c172ad97b",
  "name" : "Every thirty seconds Updated",
  "triggerType" : "SimpleTrigger",
  "triggerConfiguration" : {
    "repeatInterval" : "30000",
    "repeatCount" : "0"
  },
  "startDate" : "2016-12-10T13:11:45.666-0500",
  "endDate" : "2016-12-10T13:11:45.666-0500",
  "metadata" : { }
}Response

Sites

Sites are used to organize devices that are related so that their events can be looked at from a grouped perspective. The primary use case for sites is in location-aware devices. A site provides a containing entity to which a map can be assigned so that location data can be viewed in the context of that map.

Create New Site

Create a new site. If no token is provided in the request, a unique token will be generated automatically.

Request URI

POST/sitewhere/api/sites/

{
  "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "name" : "Construction Site",
  "description" : "Construction site that contains many heavy equipment assets",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
  "map" : {
    "type" : "mapquest",
    "metadata" : {
      "zoomLevel" : "15",
      "centerLatitude" : "34.10469794977326",
      "centerLongitude" : "-84.23966646194458"
    }
  },
  "metadata" : { }
}Request

{
  "createdDate" : "2016-12-10T13:11:45.106-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "name" : "Construction Site",
  "description" : "Construction site that contains many heavy equipment assets",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
  "map" : {
    "type" : "mapquest",
    "metadata" : {
      "zoomLevel" : "15",
      "centerLatitude" : "34.10469794977326",
      "centerLongitude" : "-84.23966646194458"
    }
  },
  "metadata" : { }
}Response

Create New Zone for Site

Create a new zone associated with the given site.

Request URI

POST/sitewhere/api/sites/{siteToken}/zones

Path Parameters

Name	Description
siteToken	Unique site token

{
  "name" : "Construction Site",
  "coordinates" : [ {
    "latitude" : 34.10260138703638,
    "longitude" : -84.24412965774536,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101837372446774,
    "longitude" : -84.24243450164795,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101517550337825,
    "longitude" : -84.24091100692749,
    "elevation" : 0.0
  }, {
    "latitude" : 34.10154953265732,
    "longitude" : -84.23856675624847,
    "elevation" : 0.0
  } ],
  "borderColor" : "#017112",
  "fillColor" : "#1db32e",
  "opacity" : 0.4
}Request

{
  "createdDate" : "2016-12-10T13:11:45.107-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "6fdaa5bc-a96a-4a65-bf01-db791e038f8b",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "name" : "Construction Site",
  "coordinates" : [ {
    "latitude" : 34.10260138703638,
    "longitude" : -84.24412965774536,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101837372446774,
    "longitude" : -84.24243450164795,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101517550337825,
    "longitude" : -84.24091100692749,
    "elevation" : 0.0
  }, {
    "latitude" : 34.10154953265732,
    "longitude" : -84.23856675624847,
    "elevation" : 0.0
  } ],
  "borderColor" : "#017112",
  "fillColor" : "#1db32e",
  "opacity" : 0.4,
  "metadata" : { }
}Response

Delete Site by Token

Delete an existing site based on its unique token. The response includes information about the site that was deleted.

Request URI

DELETE/sitewhere/api/sites/{siteToken}

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.106-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "name" : "Construction Site",
  "description" : "Construction site that contains many heavy equipment assets",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
  "map" : {
    "type" : "mapquest",
    "metadata" : {
      "zoomLevel" : "15",
      "centerLatitude" : "34.10469794977326",
      "centerLongitude" : "-84.23966646194458"
    }
  },
  "metadata" : { }
}Response

Get Site by Unique Token

Get a site based on its unique token.

Request URI

GET/sitewhere/api/sites/{siteToken}

Path Parameters

Name	Description
siteToken	Unique token that identifies site

{
  "createdDate" : "2016-12-10T13:11:45.106-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "name" : "Construction Site",
  "description" : "Construction site that contains many heavy equipment assets",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
  "map" : {
    "type" : "mapquest",
    "metadata" : {
      "zoomLevel" : "15",
      "centerLatitude" : "34.10469794977326",
      "centerLongitude" : "-84.23966646194458"
    }
  },
  "metadata" : { }
}Response

List Alerts for Site

List alerts for a site based on the given criteria. The includeXXX methods indicate the level of detail desired for related entities.

Request URI

GET/sitewhere/api/sites/{siteToken}/alerts

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "239472398473",
    "eventType" : "Alert",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.120-0500",
    "receivedDate" : "2016-12-10T13:11:45.120-0500",
    "source" : "Device",
    "level" : "Warning",
    "type" : "engine.overheat",
    "message" : "Engine temperature is at top of operating range.",
    "metadata" : { }
  }, {
    "id" : "230493483398",
    "eventType" : "Alert",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.121-0500",
    "receivedDate" : "2016-12-10T13:11:45.121-0500",
    "source" : "Device",
    "level" : "Critical",
    "type" : "fuel.level",
    "message" : "Fuel level is critical.",
    "metadata" : { }
  } ]
}Response

List Command Invocations for Site

List device command invocations for a site based on the given criteria.

Request URI

GET/sitewhere/api/sites/{siteToken}/invocations

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "230983938938",
    "eventType" : "CommandInvocation",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.121-0500",
    "receivedDate" : "2016-12-10T13:11:45.121-0500",
    "initiator" : "REST",
    "initiatorId" : "admin",
    "target" : "Assignment",
    "commandToken" : "3c1c61a3-652f-407e-80e7-fcfb13c10624",
    "parameterValues" : {
      "verbose" : "true"
    },
    "metadata" : { }
  }, {
    "id" : "239402938454",
    "eventType" : "CommandInvocation",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.122-0500",
    "receivedDate" : "2016-12-10T13:11:45.122-0500",
    "initiator" : "REST",
    "initiatorId" : "admin",
    "target" : "Assignment",
    "commandToken" : "2a3a344d-f09b-44a7-b36b-afb04993eb414",
    "parameterValues" : {
      "reboot" : "true",
      "interval" : "60"
    },
    "metadata" : { }
  } ]
}Response

List Command Responses for Site

List device command responses for a site based on the given criteria.

Request URI

GET/sitewhere/api/sites/{siteToken}/responses

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "254449849440",
    "eventType" : "CommandResponse",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.122-0500",
    "receivedDate" : "2016-12-10T13:11:45.122-0500",
    "originatingEventId" : "230983938938",
    "response" : "Firmware 1.1.0 (1.1.0.201512310800)",
    "metadata" : { }
  }, {
    "id" : "287494894849",
    "eventType" : "CommandResponse",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.123-0500",
    "receivedDate" : "2016-12-10T13:11:45.123-0500",
    "originatingEventId" : "239402938454",
    "responseEventId" : "239472398473",
    "metadata" : { }
  } ]
}Response

List Device Assignments for Site

List device assignments for a site based on the given criteria.

Request URI

GET/sitewhere/api/sites/{siteToken}/assignments

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Request Parameters

Name	Description	Required
includeAsset	Include detailed asset information	false
includeDevice	Include detailed device information	false
includeSite	Include detailed site information	false
status	Limit results to the given status	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.114-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "status" : "Active",
    "activeDate" : "2016-12-10T13:11:45.114-0500",
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.115-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "b91b8f1a-7040-475a-bf05-275418b335d8",
    "deviceHardwareId" : "b6daecc5-b0b2-48a8-90ab-4c4a170dd2a0",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "martin",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "status" : "Released",
    "activeDate" : "2016-12-10T13:11:45.115-0500",
    "releasedDate" : "2016-12-10T13:11:45.115-0500",
    "metadata" : { }
  } ]
}Response

List Locations for Site

List locations for a site based on the given criteria.

Request URI

GET/sitewhere/api/sites/{siteToken}/locations

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "203948023656",
    "eventType" : "Location",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.117-0500",
    "receivedDate" : "2016-12-10T13:11:45.117-0500",
    "latitude" : 34.103270338359664,
    "longitude" : -84.23874458667342,
    "elevation" : 0.0,
    "metadata" : { }
  }, {
    "id" : "230984233904",
    "eventType" : "Location",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.117-0500",
    "receivedDate" : "2016-12-10T13:11:45.117-0500",
    "latitude" : 34.10345084984494,
    "longitude" : -84.23983484847486,
    "elevation" : 0.1,
    "metadata" : { }
  } ]
}Response

List Measurements for Site

List measurements for a site based on the given criteria.

Request URI

GET/sitewhere/api/sites/{siteToken}/measurements

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Request Parameters

Name	Description	Required
endDate	End date	false
startDate	Start date	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "id" : "234203504574",
    "eventType" : "Measurements",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.119-0500",
    "receivedDate" : "2016-12-10T13:11:45.119-0500",
    "measurements" : {
      "engine.temperature" : 86.21,
      "fuel.level" : 32.68
    },
    "measurementsSummary" : "engine.temperature: 86.21, fuel.level: 32.68",
    "metadata" : { }
  }, {
    "id" : "230948239489",
    "eventType" : "Measurements",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "deviceAssignmentToken" : "1ad74fe3-2cbf-443f-aede-9ec70a9a4ab5",
    "assignmentType" : "Associated",
    "assetModuleId" : "ac-persons",
    "assetId" : "derek",
    "eventDate" : "2016-12-10T13:11:45.119-0500",
    "receivedDate" : "2016-12-10T13:11:45.119-0500",
    "measurements" : {
      "engine.temperature" : 84.26,
      "fuel.level" : 33.78
    },
    "measurementsSummary" : "engine.temperature: 84.26, fuel.level: 33.78",
    "metadata" : { }
  } ]
}Response

List Sites Matching Criteria

List all sites that match the given criteria.

Request URI

GET/sitewhere/api/sites/

Request Parameters

Name	Description	Required
includeZones	Include zones	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.106-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "description" : "Construction site that contains many heavy equipment assets",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.108-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "9707c31a-71b0-4fd2-8e0b-e9c7a5d249e83",
    "name" : "Vehicle Tracking Site",
    "description" : "Site that allows for tracking of a rental fleet",
    "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/airport/airport.gif",
    "map" : {
      "type" : "mapquest",
      "metadata" : {
        "zoomLevel" : "15",
        "centerLatitude" : "34.10469794977326",
        "centerLongitude" : "-84.23966646194458"
      }
    },
    "metadata" : { }
  } ]
}Response

List Zones for Site

List zones for a site based on the given criteria.

Request URI

GET/sitewhere/api/sites/{siteToken}/zones

Path Parameters

Name	Description
siteToken	Unique token that identifies site

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.107-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "6fdaa5bc-a96a-4a65-bf01-db791e038f8b",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "Construction Site",
    "coordinates" : [ {
      "latitude" : 34.10260138703638,
      "longitude" : -84.24412965774536,
      "elevation" : 0.0
    }, {
      "latitude" : 34.101837372446774,
      "longitude" : -84.24243450164795,
      "elevation" : 0.0
    }, {
      "latitude" : 34.101517550337825,
      "longitude" : -84.24091100692749,
      "elevation" : 0.0
    }, {
      "latitude" : 34.10154953265732,
      "longitude" : -84.23856675624847,
      "elevation" : 0.0
    } ],
    "borderColor" : "#017112",
    "fillColor" : "#1db32e",
    "opacity" : 0.4,
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.108-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "token" : "9707c31a-71b0-4fd2-8e0b-e9c7a5d249e8",
    "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
    "name" : "OffLimits",
    "coordinates" : [ {
      "latitude" : 34.10260138703638,
      "longitude" : -84.24412965774536,
      "elevation" : 0.0
    }, {
      "latitude" : 34.101837372446774,
      "longitude" : -84.24243450164795,
      "elevation" : 0.0
    }, {
      "latitude" : 34.101517550337825,
      "longitude" : -84.24091100692749,
      "elevation" : 0.0
    }, {
      "latitude" : 34.10154953265732,
      "longitude" : -84.23856675624847,
      "elevation" : 0.0
    } ],
    "borderColor" : "#990000",
    "fillColor" : "#660000",
    "opacity" : 0.5,
    "metadata" : { }
  } ]
}Response

Update Existing Site

Update an existing site. Only fields that are to be updated need to be passed. The device token can not be updated.

Request URI

PUT/sitewhere/api/sites/{siteToken}

Path Parameters

Name	Description
siteToken	Unique token that identifies site

{
  "name" : "Construction Site Updated."
}Request

{
  "createdDate" : "2016-12-10T13:11:46.582-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "name" : "Construction Site Updated.",
  "description" : "Construction site that contains many heavy equipment assets",
  "imageUrl" : "https://s3.amazonaws.com/sitewhere-demo/construction/construction.jpg",
  "map" : {
    "type" : "mapquest",
    "metadata" : {
      "zoomLevel" : "15",
      "centerLatitude" : "34.10469794977326",
      "centerLongitude" : "-84.23966646194458"
    }
  },
  "metadata" : { }
}Response

System Information

This service provides information about the running SiteWhere instance.

Get Server Runtime Information

# TODO

Request URI

GET/sitewhere/api/system/runtime

{
  "general" : {
    "edition" : "Community Edition",
    "editionIdentifier" : "CE",
    "versionIdentifier" : "1.3.0",
    "buildTimestamp" : "20151231120000",
    "uptime" : 107297,
    "operatingSystemName" : "Windows 8.1",
    "operatingSystemVersion" : "6.3"
  },
  "java" : {
    "jvmVendor" : "Oracle Corporation",
    "jvmVersion" : "1.7.0_79",
    "jvmFreeMemory" : 275942376,
    "jvmFreeMemoryHistory" : null,
    "jvmTotalMemory" : 576192512,
    "jvmTotalMemoryHistory" : null,
    "jvmMaxMemory" : 954728448
  }
}Response

Get Version Information

Get version information about the running SiteWhere instance.

Request URI

GET/sitewhere/api/system/version

{
  "edition" : "Community Edition",
  "editionIdentifier" : "CE",
  "versionIdentifier" : "1.3.0",
  "buildTimestamp" : "20151231120000",
  "serverClass" : null
}Response

Tenant Groups

One or more tenants can be associated by adding them to a tenant group. Tenant groups can be used to execute bulk functionality for all tenants in the group.

Tenants

SiteWhere provides an architecture where multiple IoT applications can run concurrently in separate containers. Each container is called a tenant and contains its own data and processing pipeline. Each tenant is associated with one or more system users which are allowed to configure and control it.

Create New Tenant

Create a new tenant.

Request URI

POST/sitewhere/api/tenants/

{
  "id" : "default",
  "name" : "Default Tenant",
  "authenticationToken" : "sitewhere1234567890",
  "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
  "authorizedUserIds" : [ "admin" ]
}Request

{
  "createdDate" : "2016-12-10T13:11:45.133-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "id" : "default",
  "name" : "Default Tenant",
  "authenticationToken" : "sitewhere1234567890",
  "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
  "authorizedUserIds" : [ "admin" ],
  "metadata" : { }
}Response

Delete Existing Tenant

Delete an existing tenant based on its unique id. Information about the deleted tenant is returned in the response.

Request URI

DELETE/sitewhere/api/tenants/{tenantId}

Path Parameters

Name	Description
tenantId	Tenant id

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.133-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "id" : "default",
  "name" : "Default Tenant",
  "authenticationToken" : "sitewhere1234567890",
  "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
  "authorizedUserIds" : [ "admin" ],
  "metadata" : { }
}Response

Get Tenant by Authentication Token

Get a tenant based on the unique authentication token assigned to it. Clients pass an authenticaton token to indicate which tenant they are associated with.

Request URI

GET/sitewhere/api/tenants/authtoken/{authToken}

Path Parameters

Name	Description
authToken	Authentication token

{
  "createdDate" : "2016-12-10T13:11:45.133-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "id" : "default",
  "name" : "Default Tenant",
  "authenticationToken" : "sitewhere1234567890",
  "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
  "authorizedUserIds" : [ "admin" ],
  "metadata" : { }
}Response

Get Tenant by Unique Id

Get a tenant by its unique identifier.

Request URI

GET/sitewhere/api/tenants/{tenantId}

Path Parameters

Name	Description
tenantId	Tenant id

Request Parameters

Name	Description	Required
includeRuntimeInfo	Include runtime info	false

{
  "createdDate" : "2016-12-10T13:11:45.133-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "id" : "default",
  "name" : "Default Tenant",
  "authenticationToken" : "sitewhere1234567890",
  "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
  "authorizedUserIds" : [ "admin" ],
  "metadata" : { }
}Response

Get Tenant Engine Configuration

Get the current XML configuration running for a given tenant.

Request URI

GET/sitewhere/api/tenants/{tenantId}/engine/configuration

Path Parameters

Name	Description
tenantId	Tenant id

Get Tenant Engine Configuration As JSON

# TODO

Request URI

GET/sitewhere/api/tenants/{tenantId}/engine/configuration/json

Path Parameters

Name	Description
tenantId	Tenant id

List Tenants that Match Criteria

List tenants that match the given criteria.

Request URI

GET/sitewhere/api/tenants/

Request Parameters

Name	Description	Required
authUserId	Authorized user id	false
includeRuntimeInfo	Include runtime info	false
textSearch	Text search (partial id or name)	false

Paged Results Request Parameters

Name	Description	Required
page	Page number	false
pageSize	Page size	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.133-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "id" : "default",
    "name" : "Default Tenant",
    "authenticationToken" : "sitewhere1234567890",
    "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
    "authorizedUserIds" : [ "admin" ],
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.133-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "id" : "merchant1",
    "name" : "Merchant1",
    "authenticationToken" : "m1-349384344839",
    "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
    "authorizedUserIds" : [ "admin" ],
    "metadata" : { }
  } ]
}Response

Send Command to Tenant Engine

Send a command to a tenant engine. The command is interpreted by the engine and results in a response message being returned. Current available commands include:

start - Start the tenant engine.
stop - Stop the tenant engine.

Request URI

POST/sitewhere/api/tenants/{tenantId}/engine/{command}

Path Parameters

Name	Description
command	Command
tenantId	Tenant id

{
  "result" : "Successful",
  "message" : "Tenant engine was stopped."
}Response

Stage Tenant Engine Configuration

# TODO

Request URI

POST/sitewhere/api/tenants/{tenantId}/engine/configuration/json

Path Parameters

Name	Description
tenantId	Tenant id

Update an Existing Tenant

Update an existing tenant. Only fields that are to be changed need to be passed.

Request URI

PUT/sitewhere/api/tenants/{tenantId}

Path Parameters

Name	Description
tenantId	Tenant id

{
  "name" : "Default Tenant Updated"
}Request

{
  "createdDate" : "2016-12-10T13:11:45.348-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "id" : "default",
  "name" : "Default Tenant Updated",
  "authenticationToken" : "sitewhere1234567890",
  "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
  "authorizedUserIds" : [ "admin" ],
  "metadata" : { }
}Response

Users

SiteWhere users represent entities authorized to use the system. User credentials are used to log in to the administrative console and are required for accessing the REST services. When performing create/update operations on SiteWhere entities, the username of the authenticated user is stored to indicate who performed the action.

Create New User

Create a new user.

Request URI

POST/sitewhere/api/users/

{
  "username" : "admin",
  "password" : "admin",
  "firstName" : "Admin",
  "lastName" : "User",
  "authorities" : [ "ROLE_REST", "ROLE_ADMIN_CONSOLE", "ROLE_ADMINISTER_USERS" ],
  "metadata" : { }
}Request

{
  "createdDate" : "2016-12-10T13:11:45.132-0500",
  "createdBy" : "system",
  "deleted" : false,
  "username" : "admin",
  "hashedPassword" : "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
  "firstName" : "Admin",
  "lastName" : "User",
  "lastLogin" : "2016-12-10T13:11:45.132-0500",
  "status" : "Active",
  "authorities" : [ "ROLE_REST", "ROLE_ADMIN_CONSOLE", "ROLE_ADMINISTER_USERS" ],
  "metadata" : { }
}Response

Delete User by Username

Delete an existing user based on unique username. Information about the deleted user is returned in the response.

Request URI

DELETE/sitewhere/api/users/{username:.+}

Path Parameters

Name	Description
username	Unique username

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "createdDate" : "2016-12-10T13:11:45.132-0500",
  "createdBy" : "system",
  "deleted" : false,
  "username" : "admin",
  "hashedPassword" : "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
  "firstName" : "Admin",
  "lastName" : "User",
  "lastLogin" : "2016-12-10T13:11:45.132-0500",
  "status" : "Active",
  "authorities" : [ "ROLE_REST", "ROLE_ADMIN_CONSOLE", "ROLE_ADMINISTER_USERS" ],
  "metadata" : { }
}Response

Get Authorities for User

Get the list of authorities associated with a given user.

Request URI

GET/sitewhere/api/users/{username:.+}/authorities

Path Parameters

Name	Description
username	Unique username

{
  "numResults" : 2,
  "results" : [ {
    "authority" : "REST",
    "description" : "REST services access",
    "parent" : "GRP_ACCESS",
    "group" : false
  }, {
    "authority" : "ADMINISTER_USERS",
    "description" : "Administer all users",
    "parent" : "GRP_USERS",
    "group" : false
  } ]
}Response

Get User by Username

Get user information based on unique username.

Request URI

GET/sitewhere/api/users/{username:.+}

Path Parameters

Name	Description
username	Unique username

{
  "createdDate" : "2016-12-10T13:11:45.132-0500",
  "createdBy" : "system",
  "deleted" : false,
  "username" : "admin",
  "hashedPassword" : "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
  "firstName" : "Admin",
  "lastName" : "User",
  "lastLogin" : "2016-12-10T13:11:45.132-0500",
  "status" : "Active",
  "authorities" : [ "ROLE_REST", "ROLE_ADMIN_CONSOLE", "ROLE_ADMINISTER_USERS" ],
  "metadata" : { }
}Response

List Authorized Tenants for User

List tenants which a given user is authorized manage.

Request URI

GET/sitewhere/api/users/{username:.+}/tenants

Path Parameters

Name	Description
username	Unique username

Request Parameters

Name	Description	Required
includeRuntimeInfo	Include runtime info	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.133-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "id" : "default",
    "name" : "Default Tenant",
    "authenticationToken" : "sitewhere1234567890",
    "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
    "authorizedUserIds" : [ "admin" ],
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.133-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "id" : "merchant1",
    "name" : "Merchant1",
    "authenticationToken" : "m1-349384344839",
    "logoUrl" : "https://s3.amazonaws.com/sitewhere-demo/sitewhere-small.png",
    "authorizedUserIds" : [ "admin" ],
    "metadata" : { }
  } ]
}Response

List Users Matching Criteria

List users that match the given criteria.

Request URI

GET/sitewhere/api/users/

Request Parameters

Name	Description	Required
count	Max records to return	false
includeDeleted	Include deleted	false

{
  "numResults" : 2,
  "results" : [ {
    "createdDate" : "2016-12-10T13:11:45.132-0500",
    "createdBy" : "system",
    "deleted" : false,
    "username" : "admin",
    "hashedPassword" : "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
    "firstName" : "Admin",
    "lastName" : "User",
    "lastLogin" : "2016-12-10T13:11:45.132-0500",
    "status" : "Active",
    "authorities" : [ "ROLE_REST", "ROLE_ADMIN_CONSOLE", "ROLE_ADMINISTER_USERS" ],
    "metadata" : { }
  }, {
    "createdDate" : "2016-12-10T13:11:45.132-0500",
    "createdBy" : "admin",
    "deleted" : false,
    "username" : "jdoe",
    "hashedPassword" : "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
    "firstName" : "John",
    "lastName" : "Doe",
    "lastLogin" : "2016-12-10T13:11:45.132-0500",
    "status" : "Locked",
    "authorities" : [ "ROLE_REST" ],
    "metadata" : {
      "phone.number" : "777-555-1212"
    }
  } ]
}Response

Update Existing User

Updates information for an existing user. Only fields that should be updated need to be passed.

Request URI

PUT/sitewhere/api/users/{username:.+}

Path Parameters

Name	Description
username	Unique username

{
  "firstName" : "Robert",
  "status" : "Locked"
}Request

{
  "createdDate" : "2016-12-10T13:11:45.997-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "username" : "jdoe",
  "hashedPassword" : "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8",
  "firstName" : "Robert",
  "lastName" : "Doe",
  "lastLogin" : "2016-12-10T13:11:45.997-0500",
  "status" : "Locked",
  "authorities" : [ "ROLE_REST" ],
  "metadata" : {
    "phone.number" : "777-555-1212"
  }
}Response

Zones

Zones are user-defined geospatial areas that carry special meanings in IoT applications. For instance, in an airport, there are secure areas where only certain personnel should be allowed. In an application that monitors airport security, it makes sense to be able to fire an alert if an unauthorized person enters a secure zone.

Delete Zone by Unique Token

Delete an existing zone based on its unique token. Information about the deleted zone is returned in the response.

Request URI

DELETE/sitewhere/api/zones/{zoneToken}

Path Parameters

Name	Description
zoneToken	Unique token that identifies zone

Request Parameters

Name	Description	Required
force	Delete permanently	false

{
  "name" : "Construction Site",
  "coordinates" : [ {
    "latitude" : 34.10260138703638,
    "longitude" : -84.24412965774536,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101837372446774,
    "longitude" : -84.24243450164795,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101517550337825,
    "longitude" : -84.24091100692749,
    "elevation" : 0.0
  }, {
    "latitude" : 34.10154953265732,
    "longitude" : -84.23856675624847,
    "elevation" : 0.0
  } ],
  "borderColor" : "#017112",
  "fillColor" : "#1db32e",
  "opacity" : 0.4
}Response

Get Zone by Token

Get an existing zone by unique token.

Request URI

GET/sitewhere/api/zones/{zoneToken}

Path Parameters

Name	Description
zoneToken	Unique token that identifies zone

{
  "name" : "Construction Site",
  "coordinates" : [ {
    "latitude" : 34.10260138703638,
    "longitude" : -84.24412965774536,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101837372446774,
    "longitude" : -84.24243450164795,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101517550337825,
    "longitude" : -84.24091100692749,
    "elevation" : 0.0
  }, {
    "latitude" : 34.10154953265732,
    "longitude" : -84.23856675624847,
    "elevation" : 0.0
  } ],
  "borderColor" : "#017112",
  "fillColor" : "#1db32e",
  "opacity" : 0.4
}Response

Update an Existing Zone

Update information about an existing zone. Only updated fields need to be passed in the request.

Request URI

PUT/sitewhere/api/zones/{zoneToken}

Path Parameters

Name	Description
zoneToken	Unique token that identifies zone

{
  "name" : "Construction Site Updated"
}Request

{
  "createdDate" : "2016-12-10T13:11:46.147-0500",
  "createdBy" : "admin",
  "deleted" : false,
  "token" : "6fdaa5bc-a96a-4a65-bf01-db791e038f8b",
  "siteToken" : "bb105f8d-3150-41f5-b9d1-db04965668d3",
  "name" : "Construction Site Updated",
  "coordinates" : [ {
    "latitude" : 34.10260138703638,
    "longitude" : -84.24412965774536,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101837372446774,
    "longitude" : -84.24243450164795,
    "elevation" : 0.0
  }, {
    "latitude" : 34.101517550337825,
    "longitude" : -84.24091100692749,
    "elevation" : 0.0
  }, {
    "latitude" : 34.10154953265732,
    "longitude" : -84.23856675624847,
    "elevation" : 0.0
  } ],
  "borderColor" : "#017112",
  "fillColor" : "#1db32e",
  "opacity" : 0.4,
  "metadata" : { }
}Response