{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"816e335e-2e21-44fe-87ad-56fdc7028960","name":"BASCloud API Documentation v2.1","description":"<img src=\"https://bascloud.net/wp-content/uploads/2015/12/cropped-BAS-Cloud-Logo-2019-4C-1-32x32.png\">\n\nThis is the official BAScloud API documentation. The intention of this document is to guide and support interaction with our product.\n\nThis API adapts the [JSON:API specification](https://jsonapi.org/format/).\n\nThe JSON:API specification is well documented. If you have any problems understanding the API mechanisms please refer to the official JSON:API specification ([Link](https://jsonapi.org/format/)). All mechanisms and concepts are adapted from the JSON:API. This will lead to a more stable and predictable behaviour and will reduce the number of \"Breaking Changes\" in the future.\n\n---\n\n## Changelog v2.1\n\nVersion 2.1 of the BAScloud API introduced new functionality and minor changes in the interaction for a set of endpoints. The following changes were made:\n\n- **Change in property-connector relation**  \n    The relationship between a property and connector was removed. Due to central GLTs a connector may be responsible for more than one property. A connector is now independent of properties. **Thus the property relationship entry was removed from the** _**create-connector**_ **request body. Additionally, the API routes for connector relationships of a property were deprecated. Similar, the connector routes for property relationships.** To associate devices to their located properties, a property now has a direct relationship to devices. For this, device relationship routes were added to properties. **For the create-device route, now a property relationship must be specified, besides the already existing connector relationship.**\n    \n- **New functionality for readings creation**  \n    The _create-a-reading_ route now additionally supports the creation of a set of readings at once. For this, the request body contains an array of reading definitions. See _create a set of new readings_ route documentation for examples.\n    \n- **New user role and permission endpoint**  \n    Located under the users endpoints, the \"users/permissions\" route can be used to request the users role and permissions in the associated tenant. See \"Roles and Permissions\" section for a description.\n    \n- **New connector role and permission endpoint**  \n    Located under the connectors endpoints, the \"connectors/permissions\" route can be used to request the connectors role and permissions in the associated tenant. See \"Roles and Permissions\" section for a description.\n    \n- **New creation date filter for collections**  \n    For **all** entity collections routes it is now possible to filter on the creation date, similiar to the already existing _until_ and _from_ parameters for timestamps. Two new parameters _createdUntil_, _createdFrom_ were introduced. With this, it is now possible to request entities created in a specific timespan. This may be useful for i.e. reading collections as the timestamp and creation date may differ.\n    \n- **New device attribute**  \n    A device entity now posses two AKS-ID attributes, a new optional _localAksId_ and the _aksId_. The _localAksId_ describes the AKS-ID as defined by the local infrastructure the device is located in and can optionally be specified at the device creation. The device attribute _aksId_ describes a BAScloud internal AKS-ID definition, which may be a refined version or identical (default) to the _localAksID_. When retrieving a device entity, both _localAksId_ and _aksId_ are available. For external users not located in the local infrastructure of the device, the _aksId_ should be used to identify the device. For the _device-collection_ route the new attribute _localAksId_ can be further used as filter parameter.\n    \n- **New property filter for device collections**  \n    Due to the direct relationship from a device to a property, a new filter parameter \"propertyId\" was added to the _device-collection_ route. This filter makes it possible to retrieve devices only for a specific property.\n    \n- **New property attributes**  \n    For a property entity the string attributes _aksId_ and _identifier_ were added. _AksId_ is meant to describe the part of a AKS-ID that identifies the property. _Identifier_ is a administrative identifier of the property (_Liegenschaftsnummer_). Both attributes are optional and can be specified in the _create-property_ and _update-property_ routes. For the property-collection route the new attributes can be further used as filter parameter.\n    \n- **HTTP compression support added**  \n    To decrease response delay and transmission size, HTTP compression using the gzip encoding is now available for all supporting devices. To activate compression add \"Accept-Encoding: gzip, deflate\" to the request header.\n    \n- **Connector token attribute name unified**  \n    Attribute name _apiKey_ in create-connector route changed to _token_ to be consistent with other routes. Removed attribute _apiKey_ from generate-new-token route response.\n    \n- **Count attribute in collection results unified**  \n    In all collection results the attribute _count_ is available under meta/page describing the total number of elements in the query, over all pages.\n    \n\n---\n\n## Limits\n\nAuthorized API endpoints have a request limitation of\n\n- 40 queries per second per **JWT token**\n    \n\nUnauthorized API endpoints (e.g. login) have a request limitation of\n\n- 100 queries per minute per **IP address**\n    \n\n## Pagination\n\nEach endpoint returning a collection of entities uses pagination. Therefore a top-level meta object is sent containing the pagination links. It provides links for the first site of the collection, the next page in the result set and the previous page to paginate backwards. Furthermore the current page, the total number of pages and the total number of objects over al pages are returned. The standard page size is 1000 objects. The size can be adjusted but is limited to maximal 1000 objects per page.\n\n### Parameters\n\n- **page\\[size\\]**: This parameter is used to adjust the page size. It accepts a number. If a value greater than 1000 is sent the size will automatically be set to 1000.\n    \n- **page\\[after\\]** and **page\\[before\\]**: These values determine the location of the current page in the result set. You should not set these values manually instead the system provides these values in the next and previous links attributes.\n    \n\nThese parameters are used in every request returning a collection.\n\n---\n\n## Query Parameters\n\nThe endpoints to retrieve a collection do usually accept query parameters documented at each endpoint. These are used to construct a filter and request a subset of the entire entity collection. The parameters are described in the corresponding documentation sections. Parameters that are not used by the endpoint are simply stripped out of the request. So parsing non-defined parameters will not affect the functionality of the endpoint. So be careful with the spelling of the parameters as they are ignored if they are spelled wrong.\n\n---\n\n## Content-Type\n\nThe content-type HTTP-header must be set to **application/vnd.api+json**. This is mandatory for every request in which you are sending data in the body. If the content-type does not match, a \"415 - Unsupported media type\" error response is returned. The API sets the content-type to **application/vnd.api+json** in every response that is sent back to you.\n\n---\n\n## JSON Pointer\n\nA bad request will trigger a response containing a JSON pointer. The JSON pointer will indicate the source causing the error. (Specification: [https://tools.ietf.org/html/rfc6901](https://tools.ietf.org/html/rfc6901))\n\n---\n\n## JsonWebToken (JWT)\n\nA JWT is a token which is used by the user to authenticate against the API. These tokens are base64 encoded strings which contain information about the user or connector.\n\n**All requests against the API need to contain a valid JWT token as a Bearer token in the HTTP Authentication header.**\n\n**They are not encrypted, so please store them carefully in a secure place.**\n\nJWTs are signed by the BASCloud backend which guarantees the integrity of the token. If they are changed by anyone they won't be accepted by the backend. Furthermore they expire over time. The current lifetime of a token is 24 hours. After that period of time you cannot use the token anymore. The backend will reply on an invalid token of any kind with an Unauthorized Response.\n\nFor more information about JWTs see [jwt.io](https://jwt.io).\n\n_Note: You can view the content of a token in the debugger on the site._\n\n---\n\n## Roles and Permissions\n\nThere are three different roles that define the routes and actions a user can execute against the API and tenant.\n\n### Roles\n\n- Admin: Tenant administrator\n    \n- User: Tenant user\n    \n- Connector: Connector that is responsible for set of devices\n    \n\n### Permissions\n\n| Resource | Action |  | Role |  |\n| --- | --- | --- | --- | --- |\n|  |  | Admin | Connector | User |\n| Users | GET | **✓** |  | **✓** |\n| Tenants | GET | **✓** |  | **✓** |\n|  | POST |  |  |  |\n|  | PATCH |  |  |  |\n|  | DELETE |  |  |  |\n| Properties | GET | **✓** | **✓** | **✓** |\n|  | POST | **✓** |  |  |\n|  | PATCH | **✓** |  |  |\n|  | DELETE | **✓** |  |  |\n| Connectors | GET | **✓** | **✓** | **✓** |\n|  | POST |  |  |  |\n|  | PATCH |  |  |  |\n|  | DELETE |  |  |  |\n| Devices | GET | **✓** | **✓**\\* | **✓** |\n|  | POST | **✓** | **✓** |  |\n|  | PATCH | **✓** | **✓**\\* |  |\n|  | DELETE | **✓** | **✓**\\* |  |\n| Readings | GET | **✓** | **✓**\\* | **✓**\\* |\n|  | POST | **✓** | **✓**\\* | **✓**\\* |\n|  | PATCH | **✓** | **✓**\\* |  |\n|  | DELETE | **✓** | **✓**\\* |  |\n| Setpoints | GET | **✓** | **✓**\\* | **✓**\\* |\n|  | POST | **✓** | **✓**\\* | **✓**\\* |\n|  | PATCH | **✓** | **✓**\\* |  |\n|  | DELETE | **✓** | **✓**\\* |  |\n|  |  |  |  |  |\n\n\\\\\\*access is restricted to the devices associated to the connector or user","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"15210495","collectionId":"816e335e-2e21-44fe-87ad-56fdc7028960","publishedId":"TzkzpywH","public":true,"publicUrl":"https://docs.bascloud.net","privateUrl":"https://go.postman.co/documentation/15210495-816e335e-2e21-44fe-87ad-56fdc7028960","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":"BAScloud REST API documentation"}],"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":"EF5B25"}}]}},"version":"8.10.0","publishDate":"2024-09-23T07:14:40.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"BAScloud REST API documentation","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"BAScloud Backend v2","id":"2e2a7894-a123-4c18-826f-dd776414a96e","owner":"14148192","values":[{"key":"url","value":"https://api.bascloud.net/v2","enabled":true},{"key":"token","value":"{token}","enabled":true},{"key":"tenant","value":"{tenant-uuid}","enabled":true},{"key":"email","value":"{email}","enabled":true},{"key":"password","value":"","enabled":true,"type":"default"}],"published":true}],"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/768118b36f06c94b0306958b980558e6915839447e859fe16906e29d683976f0","favicon":"https://bascloud.net/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"},{"label":"BAScloud Backend v2","value":"14148192-2e2a7894-a123-4c18-826f-dd776414a96e"}],"canonicalUrl":"https://docs.bascloud.net/view/metadata/TzkzpywH"}