{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"9f5c2693-25f9-4979-9744-dc2c85c5701b","name":"iot-public-api","description":"This document is a quick preview of the current state of the CloudRail open API for IoT.\n\nCloudRail IoT API exposes part of our internal structure to the end-user that desire to implement their interfaces and workflows. Using CloudRail IoT API, You can have the main features that CloudRail provides through the [management cloud](https://devices.cloudrail.com/) while using your programming language of choice. The API is a RESTful API based on HTTP requests and JSON responses.\n\nThis version of the API, version 0.1 is a beta preview. Changes will be made upon user feedback and bug fixes. Feel free to contact us.\n\nThe easiest way to start using the CloudRail IoT API is by clicking the **Run in Postman** button above. [Postman](https://www.getpostman.com/) is a free tool that helps developers run and debug API requests and is the source of truth for this documentation. Every endpoint you see documented here is readily available by running our Postman collection.\n\n## Need help? Feedback?\n\nOur mastermind engineers are always around. The quickest way to get help is by contacting us through support.\n\n# Responses & Errors\n\nEach response is wrapped in a `data` tag, which means if you have a response (not empty or null), it will always be within the data field. We also include a status code and success flag in the response. Responses are always in JSON format.\n\nIn contrast with the success responses, the error responses will always be wrapped in a  \n\\[comment\\]: For more information and examples go to the [data models](#DataModels) page.\n\n# More Request/Response Examples\n\nTo access more examples of request and response bodies for a given endpoint, just use the dropdown that is trickly positioned in the corner of the code component as seen in the below images:\n\n1 - Click on the dropdown\n\n<img src=\"https://content.pstmn.io/f39ef756-191f-4ea9-8ba6-deb0b81b9254/RjM1NzkxODItNkNCMy00Q0ZBLUJDOEUtRUUwNkI0MjdEN0Y3XzFfMjAxX2EuanBlZw==\">\n\n2 - Select another example\n\n<img src=\"https://content.pstmn.io/d9a9b3b0-876c-40cc-ab35-0028067087d3/N0Y2MTEyMTgtREZCNy00QjMzLUI1MDUtRjdBMzExNURBRDJDXzFfMjAxX2EuanBlZw==\">\n\n# Authentication\n\nTo authenticate you just need to generate an **Api Key**. Once you have an **Api Key** you're ready to start making API requests to the associated account. If you do not have one yet, just go to the [advanced settings](https://devices.cloudrail.com/settings) in your account config and generate an API Key for your account.\n\nAll that's required for this is to set the header in your requests:\n\n`x-api-key: YOUR_API_KEY`\n\n**WARNING: Currently the API token has no expiration date, so discretion is advised to avoid security breaches. DO NOT SHARE THE API TOKEN**\n\n# Generate an API Key\n\nTo generate the API key that will be used to authenticate the requests sent to the API, follow the steps on the main page after logging in at [https://devices.cloudrail.com/](https://devices.cloudrail.com/).\n\n1) Click on \"Account\" on the sidebar\n\n<img src=\"https://content.pstmn.io/af7b6cbd-0708-4fd9-beb3-36000a5f4405/OTkyQ0I1M0QtNTU4Mi00RDJCLTkxMjktQTU3M0JENURERjFEXzFfMjAxX2EuanBlZw==\" alt=\"\">\n\n2) Select \"Advanced\" on the account page\n\n<img src=\"https://content.pstmn.io/7439dd68-c3e0-4a05-bf42-283a0527d49f/MDBCQUZDNzgtRTlCMS00MjgyLTkzMTUtMzQxNzRCNjE5NzA3XzFfMjAxX2EuanBlZw==\" alt=\"\">\n\n3 ) Click on \"Generate Key\"\n\n<img src=\"https://content.pstmn.io/b774c0f0-2cb6-4d82-81cf-85dc93438d25/RTk5NTIwOTctNDEwMS00MEM0LUJBNDktQUQ4Mzc4NzcyRkY2XzFfMjAxX2EuanBlZw==\" alt=\"\">\n\n4) Copy the key (THE KEY VALUE WILL ONLY BE DISPLAYED ONCE PER GENERATION)\n\n<img src=\"https://content.pstmn.io/66677c35-a0c6-4395-988f-ba93a2bddb5b/MTZCNTk1QjMtMDZGQi00RTQ2LUJFRTYtMDcyRENGNDc2QkE5XzFfMjAxX2EuanBlZw==\" alt=\"\">\n\n# Device Creation Workflow\n\nTo create a device (e.g. Temperature sensor) that actually sends data to the desired service, a following steps should be done.\n\n1) **Create service credentials**: This step should be done once for each service you wish to send data from the IoT device (or send data to the IoT device). You must create a valid credential for the desired service using the POST method in the `/credentials` endpoint. This step can be skipped if the credentials for the desired service has been already created.\n\n2) **Trigger box device discovery**: To detect new devices (e.g. temperature sensors) and \"sources\" (e.g. IFM AL1303), a devices refresh/discovery has to be triggered through a GET request in the `/boxes/:box-id/refresh` endpoint. That will request the CloudRail Box(if Online) to update our database with the latest information regarding every source and sensor attached. Be aware since this is **not a synchronous** operation, thous, no value is returned from this request. This step can be skipped if no changes has been made to the box setup (no new devices were attached or removed).\n\n3) **Get last discovered devices**: Get the latest sources information that was sent to our database by the given CloudRail Box using the GET method in the `/boxes/:box-id/sources`. This will return (among other data) the latest information regarding each input of each \"source\" attached to the Box. There will be a timestamp representing the last time that information was updated.\n\n3) **Create device**: This should be done after successfully retrieving devices through the step 3, all the information regarding the identification of an input and a device will be provided. Additionally, you will have to provide information regarding the selected service, and device configuration, all those will be detailed in the given endpoints description. See \"**Devices**\" section.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"26704221","team":2390458,"collectionId":"9f5c2693-25f9-4979-9744-dc2c85c5701b","publishedId":"2s9YsGgshH","public":true,"publicUrl":"https://developer.cloudrail.com","privateUrl":"https://go.postman.co/documentation/26704221-9f5c2693-25f9-4979-9744-dc2c85c5701b","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-01-11T12:36:57.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/14c4dee31a665f31457f54c62018f1f75f475822163dfe4ecf516ac3aebdd55d","favicon":"https://cloudrail.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://developer.cloudrail.com/view/metadata/2s9YsGgshH"}