{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"45924e2f-b898-4f77-8f3b-9895fdd31fd8","name":"Senquip Cloud API Documentation","description":"[📄 Terms of Service](https://docs.senquip.com/legal_docs/SEN0001%20Rev%203.0%20-%20Senquip%20Terms%20of%20Service.pdf)\n\nWelcome to the Senquip Cloud API Docs!\n\nThe Senquip Cloud API allows you to seamlessly integrate with the Senquip platform, providing real-time access to asset data and to streamline the management of multiple devices from a central platform. Whether you need to track performance, manage diagnostics, or leverage advanced analytics, this RESTful API offers a straightforward way to interact with our cloud services.\n\nKey features include:\n\n- **Real-Time Data:** Get up-to-date information on asset status and location.\n    \n- **Device Management:** Modify device settings, network configurations, and other parameters directly via the API.\n    \n- **Provisioning:** Add new devices to your account or perform bulk updates.\n    \n\nFor our other documentation see the [Senquip Docs](https://senquip.com/homepage/products/#products-documents) page.\n\nTo contact support, please use our [contact form](https://senquip.com/homepage/company/#contact).\n\n# Authentication\n\n1. To generate API credentials you must first sign up for an account on the [Senquip Portal](https://portal.senquip.com).\n    \n2. Under **Account** settings, navigate to the **API Access** tab. Credentials can be generated using the **Generate API Credentials** button.\n    \n3. Copy the **API Key** value. This is your access token, keep it safe!\n    \n4. The Senquip Cloud API uses the **API Key** authorization type for authentication. The header `X-API-Key` must contain your unqiue access token for every request.\n    \n5. API limits apply - see the **Rates and Usage Limits** section below.\n    \n\n---\n\n# **Important Notes**\n\nTo start using the Senquip Cloud API, keep in mind:\n\n- Every request must contain a valid API Key header (see **Authentication** above).\n    \n- The API has rate and usage limits (see **Rate and usage limits** below).\n    \n- The API only responds to HTTPS-secured communications. Any requests sent via HTTP return an HTTP 301 redirect to the corresponding HTTPS resources.\n    \n- The API responds in JSON format. When an API request returns an error, it is sent in the JSON response under the **message** key.\n    \n- API authorisation requests are cached by the server for 60 seconds (per API key).\n    \n\nMost endpoints that deal with a specific device require that the Device ID is provided. This is a unique identifier for the device and consists of 9 letters and numbers. For example: **`JDA54E19F`**\n\nThe Device ID can be found printed under the lid or on the outside of the packaging box.\n\n# Getting Started\n\nThe easiest way to start using the Senquip Cloud APIs 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.\n\nFrom Postman, find the **Variables** tab and change the current value of the **token** variable with your actual API Key.\n\nGo to an API function (for example General List All Devices) and press **Send**!\n\n# Errors and Response codes\n\nHere are our standard response and error codes:\n\n| **RESPONSE CODE** | **DESCRIPTION** |\n| --- | --- |\n| `200` - **OK** | Everything worked as expected! |\n| `202` - **Accepted** | Your request is accepted and is now queued. |\n| `400` - **Bad Request** | The request was invalid or cannot be otherwise served. |\n| `401` - **Unauthorized** | There is some error during validation. You need to check your token or credentials. The API key could be missing or malformed from the request. |\n| `403` - **Forbidden** | The API key is incorrect, or you do not have access to make this request. |\n| `404` - **Not Found** | The URI requested is invalid or the resource requested does not exist. |\n| `405` - **Method Not Allowed** | The API was accessed using the wrong method. Check your HTTP method. |\n| `422` - **Unprocessable Entity** | It means the request contains incorrect syntax or cannot be fulfilled. Try checking your code for errors. |\n| `429` - **Too Many Requests** | You have exceeded the API call rate limit. |\n| `500`, `502`, `504` - **Server Errors** | Some server error has occurred. Some APIs may show this due to syntax or parameter errors. Try contacting support if this persists. |\n| `503` - **Service Unavailable** | Unexpected spike in API access traffic. The server is usually operational within the next five minutes. If the outage persists contact support. |\n\n# Rate and Usage Limits\n\nOverall API rate limits are based on how many devices in your account are on a **Hosted plan**.\n\n**Account Limits per Hosted device:**\n\n- **Rate limit:** 1 request per second\n    \n- **Daily quota:** 1000 requests per day\n    \n\nThese limits scale with the number of Hosted devices in your account. See example below.\n\nIf you have **no Hosted devices**, a minimum default limit applies to your account:\n\n- **1 request per second**\n    \n- **1000 requests per day**\n    \n\nYour rate and quota limits are automatically recalculated every 12 hours based on the current number of Hosted devices.\n\nIf you exceed your limit, the API will return `HTTP 429 - Too Many Requests`\n\n### API Access for Devices Without a Hosted Plan\n\nDevices without a Hosted plan can still be accessed via API, but there is an addtional limit:\n\n- **50 requests per non-Hosted device per calendar month**\n    \n\nWhen this monthly limit applies, responses will include an `apiRequestsRemaining` value.\n\nThis limit is intended to allow occasional configuration changes. If you need higher usage, you should upgrade the device to a Hosted plan.\n\nThe only exception to the 50 request/month limit is for requesting measurement data from a device using the _Get Device Data_ endpoint. For this endpoint the device **must** either have a **Trial or Hosted Plan.**\n\nHosted plans can be purchased from the **Subscriptions** button on the home page of the Senquip Portal.\n\n### **API Limit Example**\n\nIf your account has 15 devices and 9 of them are on a Hosted plan, your total API limit is:\n\n- 9 requests per second\n    \n- 9000 requests per day\n    \n- The 6 devices without a Hosted plan will accept 50 requests per month each.\n    \n\nTo contact support or report a bug, please use our [contact form](https://senquip.com/homepage/company/#contact).\n\n# Example: Add / Register a new device\n\nAdding or registering a new device to the Senquip Portal for the first time is the same as the '_Add a User to a Device_' process:\n\n1. For a new device, no passwords are required to add the unit. Only the 9 digit Device ID is required.\n    \n2. Use the _'Add a User to a Device'_ endpoint. No body parameters are required, however it is recommended to specify the `groupid` or `groupName` as a minimum.\n    \n3. If successful the device will be added/registered to your Portal account and you can now use other API endpoints or the Senquip Portal to interact with it. If you receive the response _'Password Required'_, then the device has already been added to an account and you will need to provide the `setupPassword` body parameter in your request.\n    \n\n# Example: **Client certificates for MQTT**\n\nTo load unique client certificates on to a device:\n\n1. Load each required certificate file using the '_Load File onto Device_' endpoint. This step may require up to three seperate calls to load the files: '_mqtt_client.key_', '_mqtt_client.crt_' and '_mqtt_ca.pem_'.\n    \n2. Update the config on the device to use the certificates using the '_Update Device Config_' endpoint. An example request body:\n    \n\n``` json\n{\n  \"config\": {\n    \"endpoint\": {\n      \"mqtt\": {\n        \"enable\": true,\n        \"server\": \"mqtt.broker.address:8883\",\n        \"client_id\": \"SETYOURID\",\n        \"ssl_cert\": \"mqtt_client.crt\",\n        \"ssl_key\": \"mqtt_client.key\",\n        \"ssl_ca_cert\": \"ca.pem\"\n      }\n    }\n  }\n}\n\n ```\n\nIn this example config the _Internal Trust Store_ is used for the CA certificate instead of _mqtt_ca.pem_. The _Internal Trust Store_ on the device contains a small set of AWS and Azure certificates and always has the filename '_ca.pem_'.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"33042968","team":6417402,"collectionId":"45924e2f-b898-4f77-8f3b-9895fdd31fd8","publishedId":"2sAXxWYoWa","public":true,"publicUrl":"https://cloud-api-docs.v2.senquip.com","privateUrl":"https://go.postman.co/documentation/33042968-45924e2f-b898-4f77-8f3b-9895fdd31fd8","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"00afc9"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"The Senquip Cloud API allows you to seamlessly integrate with the Senquip platform, providing real-time access to asset data and to streamline the management of multiple devices from a central platform."},{"name":"title","value":""}],"appearance":{"default":"system_default","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"00afc9"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"00afc9"}}]}},"version":"8.10.1","publishDate":"2024-10-18T08:53:04.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":"The Senquip Cloud API allows you to seamlessly integrate with the Senquip platform, providing real-time access to asset data and to streamline the management of multiple devices from a central platform."},"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/8928b7f477f68cd3670a34dadc98de916084355d79bf9543f0753ea4bc703d8a","favicon":"https://res.cloudinary.com/postman/image/upload/v1725429081/team/0904999b9ecc3c2d8f7a4184a2b66853.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://cloud-api-docs.v2.senquip.com/view/metadata/2sAXxWYoWa"}