{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"d2b7c876-df53-40e6-8774-dbd972e41fb6","name":"akenza API","description":"akenza provides a REST API for programmatic access to its features. If you have any questions or want to request new API features, please submit a feature request on our [feedback board](https://feedback.akenza.io).\n\nSee the navigation sidebar for the list of available endpoints. Some requests have multiple examples; use the dropdown on the right to switch between example requests and responses.\n\nAll endpoints are served from `https://api.akenza.io` (the `{{baseUrl}}` variable of the **Production** environment). More guides are available in the [akenza documentation](https://docs.akenza.io/reference/api-documentation), and example code in [Python](https://github.com/akenza-io/akenza-python-examples), [JavaScript](https://github.com/akenza-io/akenza-javascript-examples) and [Java](https://github.com/akenza-io/akenza-java-examples).\n\n# Authentication\n\nakenza supports two credential types for machine-to-machine access: **API keys** and **OAuth2 clients**. Both use the same permission model: credentials are scoped to an organization, optionally restricted to specific workspaces, and carry a fine-grained set of permissions. Requests outside of the granted permissions are rejected with `403 Permission denied`.\n\n|  | API keys | OAuth2 clients |\n| --- | --- | --- |\n| Authentication | Static secret in the `x-api-key` header | Short-lived bearer token from the OAuth2 client credentials grant |\n| Token lifetime | n/a (key is long-lived) | 15 minutes |\n| Secret rotation | Delete and recreate the key | Rotate the client secret in place |\n\nDo not combine authentication methods: a request carrying both an `Authorization` header and an `x-api-key` header is rejected.\n\n## API keys\n\nAPI keys are managed in the akenza console under **API Keys** and can only be created and viewed by organization owners and administrators. Send the key in the `x-api-key` header of every request.\n\nIn Postman, this collection is configured with API key authentication: set the `apiKey` variable of your environment and all requests inherit it.\n\n## OAuth2 clients\n\nOAuth2 clients use the standard OAuth2 client credentials grant (OpenID Connect). They are managed at the organization level (`/v3/oauth-clients`, requires the organization `manage` permission). To obtain an access token, send a form-encoded `POST` to the token endpoint `https://login.akenza.io/realms/api-keys/protocol/openid-connect/token` with the fields `grant_type` (set to `client_credentials`), `client_id` and `client_secret`.\n\nThen send the access token as a bearer token in the `Authorization` header. Tokens are valid for 15 minutes and there are no refresh tokens: cache the token, reuse it across requests and request a new one shortly before it expires. Discovery metadata is published at `https://login.akenza.io/realms/api-keys/.well-known/openid-configuration`.\n\n## Permissions\n\nEach entry in `permissions` maps a scope to a list of verbs (`create`, `read`, `update`, `delete`, `manage`). Available scopes: `organization` (read is always granted), `organization.member`, `workspace`, `workspace.member`, `asset`, `deviceType`, `dataFlow`, `integration`, `rule`, `customLogic`, `deviceCredential`, `dashboard`, `dashboard.group`, `billing`, `blob`, `dataFusionLayer`.\n\n## Troubleshooting\n\n| Symptom | Cause and fix |\n| --- | --- |\n| `401 invalid token` | The token expired, or the OAuth2 client was deleted. Request a new token. |\n| `401 Two authentication headers received` | The request carries both `Authorization` and `x-api-key`. Send exactly one. |\n| `401 invalid_client` from the token endpoint | Wrong `client_id` or `client_secret`. |\n| `403 Permission denied` | The credential lacks the required scope, verb or workspace. Check its permissions. |\n\n# Errors\n\nErrors are returned as a JSON object with the HTTP status and a reason. Include the `requestId` and `errorId` when contacting support.\n\n```\n{\n    \"timestamp\": \"2021-02-19T15:06:56.928+00:00\",\n    \"path\": \"/v3/assets\",\n    \"status\": 403,\n    \"error\": \"Forbidden\",\n    \"message\": \"Permission denied\",\n    \"requestId\": \"64fa58b0-18361\",\n    \"errorId\": \"33a00d16-6a22-4687-99ca-90bb448e5eb2\",\n    \"traceId\": \"8a7c4ea8ae80a5e4\"\n}\n ```\n\n# Rate limiting\n\nRate Limiting is setup as follows (per second):\n\n```\nreplenish-rate: 10\nburst-capacity: 25\n\n ```\n\nInformation about how many requests can still be made in the next second can be found in the `X-RateLimit-Remaining` header of the response.\n\n# Pagination\n\nMost of the endpoints that return lists of objects support pagination. A client may pass the following query parameters to control pagination on supported endpoints:\n\n| **Parameter** | **Description** | **Default** |\n| --- | --- | --- |\n| page | Optional. The index of the page. | 0 |\n| size | Optional. The number of elements per page. | 20 |\n| sort | Optional. Sort order as `field,direction`, e.g. `name,asc`. |  |\n\nPaginated endpoints return the following response structure:\n\n```\n{\n    \"content\": [...],\n    \"pageable\": {\n        \"sort\": {\n            \"empty\": true,\n            \"sorted\": false,\n            \"unsorted\": true\n        },\n        \"offset\": 0,\n        \"pageSize\": 20,\n        \"pageNumber\": 0,\n        \"unpaged\": false,\n        \"paged\": true\n    },\n    \"totalPages\": 2,\n    \"totalElements\": 31,\n    \"last\": false,\n    \"size\": 20,\n    \"number\": 0,\n    \"sort\": {\n        \"empty\": true,\n        \"sorted\": false,\n        \"unsorted\": true\n    },\n    \"numberOfElements\": 20,\n    \"first\": true,\n    \"empty\": false\n}\n\n ```\n\n# Filtering\n\nList endpoints that support filtering (currently `POST /v3/assets/list`, see **Inventory**) accept a filter expression in the request body. The filterable fields, their types and supported predicates are returned by the filter options endpoint (`/v3/assets/filter-options-v2`).\n\nAn expression is either a **filter** (`field`, `predicate`, `values`) or an **expression list** that combines up to three levels of expressions with the `AND` or `OR` operator:\n\n```\n{\n    \"organizationId\": \"<organizationId>\",\n    \"search\": \"abc\",\n    \"expression\": {\n        \"operator\": \"AND\",\n        \"expressions\": [\n            { \"field\": \"id\", \"predicate\": \"IN\", \"values\": [\"<deviceId1>\", \"<deviceId2>\"] },\n            {\n                \"operator\": \"OR\",\n                \"expressions\": [\n                    { \"field\": \"name\", \"predicate\": \"STARTS_WITH\", \"values\": [\"meeting\"] },\n                    { \"field\": \"name\", \"predicate\": \"ENDS_WITH\", \"values\": [\"room\"] }\n                ]\n            },\n            { \"field\": \"customFields\", \"predicate\": \"EQUALS\", \"stringValues\": [\"Zurich\"], \"customFieldName\": \"Location\" },\n            { \"field\": \"tags.name\", \"predicate\": \"CONTAINS_ALL\", \"values\": [\"test\"] }\n        ]\n    }\n}\n\n ```\n\n| **Predicate** | **Values** | **Description** |\n| --- | --- | --- |\n| EQUALS / NOT_EQUALS | 1 | Exact match (case-insensitive for strings) / its inverse, including null values |\n| IN / NOT_IN | 1+ | Field value matches one of the values / none of the values |\n| LESS_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUALS | 1 | Numeric comparison |\n| BETWEEN | 2 | Field value lies between the two values (in any order) |\n| CONTAINS_ALL / CONTAINS_ANY / CONTAINS_NONE | 1+ | List field contains all / any / none of the values |\n| CONTAINS, STARTS_WITH, ENDS_WITH | 1 | String matching |\n| BEFORE / AFTER | 1 | Date comparison |\n| IS_NULL / IS_NOT_NULL | 0 | Field value is not set / is set |\n\n# Querying device data\n\nData stored in the akenza database can be retrieved with the endpoints in the **Query** folder. Choose the endpoint by what you need:\n\n| **Use case** | **Endpoint** |\n| --- | --- |\n| Raw samples of one device | `POST /v3/devices/{deviceId}/query` |\n| A single value (e.g. the average) of one device, timespan under 24 h | `POST /v3/devices/{deviceId}/query/raw/kpi` |\n| A single value of one device, longer timespans | `POST /v3/devices/{deviceId}/query/aggregated/hourly/kpi` |\n| A time series of one device, timespan under 24 h | `POST /v3/devices/{deviceId}/query/raw/time-series` |\n| A time series of one device, longer timespans | `POST /v3/devices/{deviceId}/query/aggregated/hourly/time-series` |\n| One value per device of a tag | `POST /v3/tags/{tagId}/query/raw/kpi` or `.../aggregated/hourly/kpi` |\n| One value accumulated across the devices of a tag | `POST /v3/tags/{tagId}/query/raw/accumulated-kpi` or `.../aggregated/hourly/accumulated-kpi` |\n| One value or time series per device for a list of devices | `POST /v3/devices/query/batch/raw/kpi`, `.../raw/time-series`, `.../aggregated/hourly/kpi` or `.../aggregated/hourly/time-series` (same body as the single-device queries, plus `deviceIds`) |\n\nakenza automatically generates hourly aggregates of all data, which makes the `aggregated/hourly` endpoints efficient for longer timespans. Querying requires the `asset` `read` permission.\n\n```\n{\n    \"topic\": \"climate\",\n    \"dataKey\": \"temperature\",\n    \"accumulator\": \"MAX\",\n    \"bucketInterval\": \"PT1H\",\n    \"interval\": {\n        \"from\": \"2023-06-30T00:00:00.000Z\",\n        \"to\": \"2023-06-30T18:00:00.000Z\"\n    }\n}\n\n ```\n\n**Accumulators:** `MIN`, `MAX`, `AVG`, `SUM`, `COUNT`, `FIRST`, `LAST` (or `NONE`), `DISTINCT_COUNT` (unique string values), `MATCHED_COUNT` / `UNMATCHED_COUNT` (number of `true` / `false` values) and `OCCUPANCY` (time-based occupancy in %, normalized to the workspace's working hours if configured).\n\n**Bucket intervals** resample time series and use the ISO-8601 duration format (e.g. `PT1H`, `P1D`). For hourly aggregates the minimum is `PT1H`. Choose the interval so that no more than 730 buckets are returned.\n\nIf your application needs all data as it arrives, polling the REST API is not the recommended approach: use an output connector (Kafka, Azure Event Hubs, AWS Kinesis, GCP Pub/Sub, SQL database, etc.) to have data forwarded to your application instead.\n\n# Backfilling data\n\nThe endpoints in **Inventory › Data ingestion** add data to a device, individually or in bulk. Backfilled data is processed by the output connectors and rules, so the body must match the output of the device type script. If not specified, `timestamp` defaults to the current time and `topic` to `default`.\n\n# Schema inference\n\n`GET /v3/devices/{deviceId}/infer-schema` returns the data schema of a device per topic, combined from the device type schema and the data the device actually measured. It returns at most 50 topics.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"6536646","team":261305,"collectionId":"d2b7c876-df53-40e6-8774-dbd972e41fb6","publishedId":"Tz5iBMRQ","public":true,"publicUrl":"https://docs.api.akenza.io","privateUrl":"https://go.postman.co/documentation/6536646-d2b7c876-df53-40e6-8774-dbd972e41fb6","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"437df7"},"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":"437DF7"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"437df7"}}]}},"version":"8.12.12","publishDate":"2024-01-15T10:48:56.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"Production","id":"c4339491-e434-4a21-922b-dae01e6b22ba","owner":"6536646","values":[{"key":"baseUrl","value":"https://api.akenza.io","enabled":true,"type":"default"},{"key":"apiKeyHeaderName","value":"x-api-key","enabled":true,"type":"default"},{"key":"dataGatewayUrl","value":"https://data-gateway.akenza.io","enabled":true,"type":"default"},{"key":"apiKey","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://postman-image-service.postman.com/api/cloudinary-proxy/postman/image/upload/t_team_logo_pubdoc/v1/team/f3185153eb934d17478447d9f66dac27e22878b5989051f8cc67dcda47cf5d56","favicon":"https://akenza.io/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":"Production","value":"6536646-c4339491-e434-4a21-922b-dae01e6b22ba"}],"canonicalUrl":"https://docs.api.akenza.io/view/metadata/Tz5iBMRQ"}