Community Tip - If community subscription notifications are filling up your inbox you can set up a daily digest and get all your notifications in a single email. X
Access to functions and information on the ThingWorx Foundation server is controlled by Users. The REST API can be used to create, list, and delete Users.
The REST API exposes the ability to retrieve collections of Entities so that a UI can be dynamically updated with current data.
〈Server IP:port〉/Thingworx/Users
Authenticate Request. All API requests to the ThingWorx server must be authenticated either with a username and password or with an appKey. For this example we will authenticate by passing the appKey as a URL query string parameter. The parameter appKey is recognized by the ThingWorx server as an authentication credential in requests, it can be passed either as a URL query string parameter .../CreateThing?appKey=64b87... , or as request header appKey: 64b87...
It is possible for the content to be returned in four different formats by sending an Accept header with the request.
Desired Response Type | Accept Header Values |
JSON | application/json |
XML | text/xml |
HTML | text/html (or omit Accept Header) |
CSV | text/csv |
http -v -j http://52.201.57.6/Thingworx/Users appKey==64b879ae-2455-4d8d-b840-5f5541a799ae Accept:text/csv
You should expect to get back the status code of 200 - OK either with or without content. In the case of an error, you will receive an error message. You can use the following table to diagnose the issue.
Response Code | Definition |
401 - Unauthorized | appKey is incorrect or missing |
403 - Forbidden | Content-Type request header is not set to application/json Sometimes returned instead of a 404 A Property with that name already exists on the platform |
404 - Not Found | Incorrect URL or API endpoint Thing or Property has not been created Incorrect ThingTemplate name Required parameter missing from request |
405 - Invalid Request | Incorrect request verb; for example a GET was used instead of PUT or POST |
406 - Not Acceptable | Invalid JSON in PUT or POST request Thing [ Thing name ] already exists: A Thing with that name already exists on the platform |
500 - Internal Server Error | Content-Type request header is not set for a service execution POST, required even without a POST body Content-Type request header is not set for DELETE request, required despite the fact that DELETE does not send any content |
503 - Service Unavailable | Thing [] is not running RestartThing endpoint must be called Thing [] is not enabled EnableThing endpoint must be called |
There are different ways to authorize requests.
We recommend you place the appKey in the HTTP request header rather than passing the appKey as a URL parameter. This prevents the appKey from being written into server log files that may be seen by someone who is not authorized to modify the ThingWorx server.
http -v -j http://iotboston.com:8887/Thingworx/Things/aTestThing/Properties/CurrentTemp appKey:d0a68eff-2cb4-4327-81ea-7e71e26
GET /Thingworx/Things/AllenTestThingFour/Properties/CurrentTemp HTTP/1.1 Accept: application/json, */* Accept-Encoding: gzip, deflate Connection: keep-alive Content-Type: application/json Host: iotboston.com:8887 appKey: d0a68eff-2cb4-4327-81ea-7e71e26bb
To send an appkey in a URL request string parameter, check the Allow Application Key as URL Parameter checkbox in the PlatformSubsystem Configuration. If the ThingWorx server is using HTTPS, the parameter will be encrypted in transit, however the appKey may be comprised because full request URLs are often written to server log files.
http -v -j http://iotboston.com:8887/Thingworx/Things/AllenTestThingFour/Properties/CurrentTemp appKey==d0a68eff-2cb4-4327-81ea-7e71e26bb645
GET /Thingworx/Things/aTestThing/Properties/CurrentTemp?appKey=d0a68eff-2cb4-4327-81ea-7e71e26 HTTP/1.1 Accept: application/json, */* Accept-Encoding: gzip, deflate Connection: keep-alive Content-Type: application/json Host: iotboston.com:8887
We do not recommend Basic Auth, because the username and password used are NOT encrypted and could be used to log into the ThingWorx platform. To demonstrate that username and password are not encrypted, copy the string in the Authorization line after Basic to Base64 Decode then click DECODE.
http -v -j http://iotboston.com:8887/Thingworx/Things/aTestThing/Properties/CurrentTemp -a Administrator:password1
GET /Thingworx/Things/AllenTestThingFour/Properties/CurrentTemp HTTP/1.1 Accept: application/json, */* Accept-Encoding: gzip, deflate Authorization: Basic QWRtaW5pc3RyYXRvcjpwYXNzd29yZDE= Connection: keep-alive Content-Type: application/json Host: iotboston.com:8887
Congratulations! You've successfully completed the Use REST API to Access ThingWorx guide.
You learned how to use the REST API to:
The next guide in the Connect and Configure Industrial Devices and Systems learning path is Java SDK Tutorial.
We recommend the following resources to continue your learning experience:
Capability | Guide |
Build | Data Model Introduction |
If you have questions, issues, or need additional information, refer to:
Resource | Link |
Community | Developer Community Forum |
Support | REST API Help Center |