From e4cb167320285b3ae0e0df89056f3aa14b78b263 Mon Sep 17 00:00:00 2001 From: Destry Teeter Date: Mon, 5 Oct 2026 11:13:47 -0700 Subject: [PATCH 1/2] Incorporate API spec v65 changes into the SDK; release 1.0.3 - Update docs/api specs (admin, bots, cloud) to server API v65 - Locations: add get/create/update_escalation for the new /cloud/json/escalations endpoints; escalation_id filter on get_narratives - DeviceTypesAndParameters: add_default_rule requires location_id (breaking) - Remove Weather and admin Challenges API classes (endpoints dropped) - Remove UserAccounts user code methods and bot Analytic.get_challenge_participants (endpoints dropped) - Drop simple/organization_id from get_device_types and get_card from get_location_service_plans - Docstrings: question permissions, service plan locationId requirement - Update docs, caredaily skill, and okf bundle; bump version to 1.0.3 Co-Authored-By: Claude Opus 5.5 (1M context) --- .claude/skills/caredaily/SKILL.md | 4 +- CHANGELOG.md | 21 + CLAUDE.md | 2 +- docs/CARE_DAILY_APIS.md | 2 - docs/api/admin.yaml | 604 +- docs/api/bots.yaml | 326 +- docs/api/cloud.yaml | 20260 ++++++++-------- okf/apis/api-surface.md | 14 +- okf/log.md | 4 + pyproject.toml | 2 +- src/caredaily/__init__.py | 6 +- src/caredaily/apis/__init__.py | 4 - src/caredaily/apis/admin/__init__.py | 2 - src/caredaily/apis/admin/challenges.py | 282 - src/caredaily/apis/app/__init__.py | 2 - .../apis/app/device_types_and_parameters.py | 9 +- src/caredaily/apis/app/locations.py | 140 +- src/caredaily/apis/app/paid_services.py | 6 +- src/caredaily/apis/app/user_accounts.py | 87 - src/caredaily/apis/app/weather.py | 154 - src/caredaily/apis/bot/analytic.py | 42 +- src/caredaily/caredaily.py | 6 - tests/caredaily/apis/admin/test_challenges.py | 137 - .../app/test_device_types_and_parameters.py | 15 +- tests/caredaily/apis/app/test_locations.py | 67 + .../caredaily/apis/app/test_paid_services.py | 3 +- .../caredaily/apis/app/test_user_accounts.py | 43 - tests/caredaily/apis/app/test_weather.py | 200 - tests/caredaily/apis/bot/test_analytic.py | 14 - tests/caredaily/test_caredaily.py | 4 - 30 files changed, 10098 insertions(+), 12364 deletions(-) delete mode 100644 src/caredaily/apis/admin/challenges.py delete mode 100644 src/caredaily/apis/app/weather.py delete mode 100644 tests/caredaily/apis/admin/test_challenges.py delete mode 100644 tests/caredaily/apis/app/test_weather.py diff --git a/.claude/skills/caredaily/SKILL.md b/.claude/skills/caredaily/SKILL.md index f88edc0..ed400a7 100644 --- a/.claude/skills/caredaily/SKILL.md +++ b/.claude/skills/caredaily/SKILL.md @@ -117,8 +117,8 @@ Import from `caredaily.apis` (or the subpackage): CloudConnectivity, CloudsIntegration, DeviceFiles, DeviceMeasurements, Devices, DeviceTypesAndParameters, EnergyManagement, Locations, PaidServices, ProfessionalMonitoring, RAG, Rules, SystemAndUserProperties, UserAccounts, - UserCommunication, Weather, Websocket -- **`admin_api`** (`caredaily.apis.admin`): Billing, Challenges, AdminDevices, + UserCommunication, Websocket +- **`admin_api`** (`caredaily.apis.admin`): Billing, AdminDevices, Firmware, Groups, AdminLocations, Narratives, Organizations, Reports, System, AdminTags, UserGroups, Users - **`bot_api`** (`caredaily.apis.bot`): Analytic, BotDeveloper, BotStore, diff --git a/CHANGELOG.md b/CHANGELOG.md index 249036e..8558574 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [1.0.3] - 2026-10-05 + +### Added +- Locations: `get_escalations`, `create_escalation`, and `update_escalation` + for the new `/cloud/json/escalations` endpoints +- Locations: `escalation_id` filter on `get_narratives`; narratives can carry an + `escalationId` in `put_narrative` + +### Changed +- API specs (cloud, admin, bots) updated to server API v65 +- DeviceTypesAndParameters: `add_default_rule` now requires `location_id` + (breaking) + +### Removed +- Weather API class (all `/cloud/json/weather/...` endpoints removed from the spec) +- Admin Challenges API class (`/admin/json/organizations/{organizationId}/challenges...`) +- Bot Analytic: `get_challenge_participants` (`/analytic/admin/challenges/{challengeId}/participants`) +- UserAccounts: `put_user_code`, `get_user_codes`, `delete_user_code` (`/cloud/json/userCodes`) +- DeviceTypesAndParameters: `simple` and `organization_id` on `get_device_types` +- PaidServices: `get_card` on `get_location_service_plans` + ## [1.0.2] - 2026-09-11 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index a6ea34d..2b319d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -70,7 +70,7 @@ auth = cd.app_api(Authentication) # also: cd.admin_api(...), cd.bot_api(...) Each factory (`app_api`, `admin_api`, `bot_api`) is an explicit if-chain over known classes and returns `None` for unknown types. **When adding a new API class**, you must (1) create it under the right `apis/` subpackage, (2) export it from `apis/__init__.py`, and (3) add it to the matching factory chain in `caredaily.py`. API subpackages: -- `apis/app/` — user-facing APIs (Authentication, Locations, Devices, DeviceMeasurements, Rules, Weather, RAG, Websocket, ...) +- `apis/app/` — user-facing APIs (Authentication, Locations, Devices, DeviceMeasurements, Rules, RAG, Websocket, ...) - `apis/admin/` — administrative APIs (System, Organizations, Users, Billing, Firmware, Reports, ...) - `apis/bot/` — bot developer APIs (BotDeveloper, BotStore, DeveloperTeams, Analytic, Execution) diff --git a/docs/CARE_DAILY_APIS.md b/docs/CARE_DAILY_APIS.md index 287b7ac..ff8a51a 100644 --- a/docs/CARE_DAILY_APIS.md +++ b/docs/CARE_DAILY_APIS.md @@ -37,7 +37,6 @@ Application-level APIs for standard user operations: - **SystemAndUserProperties** - System and user property management - **UserAccounts** - User account management - **UserCommunication** - User messaging and communication -- **Weather** - Weather data integration - **Websocket** - WebSocket connections and real-time updates ### Administrative APIs (`admin/`) @@ -45,7 +44,6 @@ Application-level APIs for standard user operations: Administrative APIs requiring admin privileges: - **Billing** - Billing and subscription management -- **Challenges** - Challenge management - **Devices** (AdminDevices) - Administrative device management - **Firmware** - Firmware management and updates - **Groups** - Organization group management diff --git a/docs/api/admin.yaml b/docs/api/admin.yaml index d966f24..48f38b6 100644 --- a/docs/api/admin.yaml +++ b/docs/api/admin.yaml @@ -1,7 +1,7 @@ openapi: 3.1.1 info: title: 'IoT Software Suite: Admin API' - version: '63' + version: '65' description: |- Care Daily offers a full Command Center to engage your customers and manage IoT services, and access to social engagement layers. @@ -126,7 +126,7 @@ paths: description: features: type: string - description: Available features for this organization:
m - messages
c - challenges + description: Available features for this organization:
m - messages deviceTypes: type: string description: Types of devices managed in this organization @@ -3289,604 +3289,6 @@ paths: resultCode: 0 - /admin/json/organizations/{organizationId}/challenges: - post: - summary: Create a Challenge - operationId: Create a Challenge - description: |- - Create a challenge from scratch or from a template. - - In a community social network setting, an Engagement Manager may issue challenges to the community, to help achieve the overall goals of the community. - - Challenges are a really fun way to engage with a large population! - tags: - - Challenges - security: - - adminApiKey: [] - parameters: - - name: organizationId - in: path - description: Organization ID to create this challenge for - required: true - schema: - type: integer - - name: check - in: query - description: >- - true - Check if an active challenge already exists without creating one.
- false - Do not check if an active challenge already exists, just create it, default. - schema: - type: boolean - - name: parentId - in: query - description: Challenge or template ID to copy settings from. - schema: - type: integer - requestBody: - content: - application/json: - example: - challenge: - name: DR event - template: false - startDate: '2014-08-01T00:00:00Z' - endDate: '2014-10-15T12:00:00Z' - challengeType: 4 - recurring: 0 - invitational: true - deviceTypeExistance: 2 - deviceTypes: - - 10 - - 20 - - 30 - excludeDeviceTypes: - - 40 - participantType: 1 - participationStatus: 1 - participantTag: auto-opt-in - excludeParticipantTag: inactive - parameters: - name1: value1 - name2: value2 - schema: - type: object - properties: - challenge: - type: object - properties: - name: - type: string - template: - type: boolean - description: |- - `True` means the challenge is intended to be used as a template for creating new challenges. In this case, participants are not created.
- Optional, default is false. - startDate: - type: string - endDate: - type: string - challengeType: - type: integer - description: 4 - Demand response - recurring: - type: integer - description: |- - 0 - One-time, not recurring
- 3 - Recurring monthly - invitational: - type: boolean - deviceTypeExistance: - type: integer - description: |- - Optional, default is 0.
- 1 - ANY listed device type must exists on the participating location
- 2 - ALL device types must exist on the participating location - deviceTypes: - type: array - description: A list of device types to filter participants - items: - type: integer - excludeDeviceTypes: - type: array - description: Exclude locations having any of these devices from the challenge - items: - type: integer - participantType: - type: integer - description: 1 - Individual challenge - participationStatus: - type: integer - description: |- - Initial participation status for invited users.
- 1 - Not responded, default
- 2 - Opt-In
- 3 - Opt-Out - participantTag: - type: string - description: A tag value to filter participants. - excludeParticipantTag: - type: string - description: Exclude locations having this tag - parameters: - type: object - description: Parameters key/value string map - additionalProperties: - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - challengeId: - type: integer - example: - resultCode: 0 - challengeId: 123 - - get: - summary: Get Challenges - operationId: Get Challenges - description: >- - View a list of challenges selected by their parameters. - Only admins can see the templates in the search results. - tags: - - Challenges - security: - - userApiKey: [] - parameters: - - name: organizationId - in: path - description: Organization ID to retrieve challenges for - required: true - schema: - type: integer - - name: status - in: query - description: >- - Optional status filter
- 0 - Inactive
- 1 - Active
- 2 - Completed - schema: - type: integer - - name: challengeId - in: query - description: Retrieve only this challenge - schema: - type: integer - - name: challengeType - in: query - description: Filter response by challenge types. Multiple values are supported. - schema: - type: integer - - name: searchBy - in: query - description: Search by name - schema: - type: string - - name: parentId - in: query - description: Template ID to filter by - schema: - type: integer - responses: - '200': - description: Challenges - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - challenges: - type: array - items: - type: object - properties: - challengeId: - type: integer - template: - type: boolean - parentId: - type: integer - name: - type: string - startDate: - type: string - startDateMs: - type: integer - challengeType: - type: integer - recurring: - type: integer - participantType: - type: integer - status: - type: integer - invitational: - type: boolean - deviceTypes: - type: array - items: - type: integer - deviceTypeExistance: - type: integer - participantTag: - type: string - excludeDeviceTypes: - type: array - items: - type: integer - excludeParticipantTag: - type: string - participantsIn: - type: integer - participantsOut: - type: integer - participantsNoResponse: - type: integer - parameters: - type: object - description: Parameters key/value string map - additionalProperties: - type: string - endDate: - type: string - endDateMs: - type: integer - required: - - challengeId - - name - - startDate - - startDateMs - - challengeType - - recurring - - status - - template - example: - resultCode: 0 - challenges: - - challengeId: 90 - template: false - parentId: 50 - name: DR event - startDate: '2014-08-14T22:23:10-04:00' - startDateMs: 1408069390000 - challengeType: 4 - recurring: 0 - participantType: 1 - status: 1 - invitational: true - deviceTypes: - - 10 - - 20 - - 30 - deviceTypeExistance: 2 - participantTag: auto-opt-in - excludeDeviceTypes: - - 40 - excludeParticipantTag: inactive - participantsIn: 60 - participantsOut: 20 - participantsNoResponse: 10 - parameters: - name1: value1 - name2: value2 - - challengeId: 127 - name: template - startDate: '2014-06-30T14:30:00-04:00' - startDateMs: 1404153000000 - endDate: '2014-07-31T14:29:59-04:00' - endDateMs: 1406831399000 - challengeType: 4 - recurring: 0 - participantType: 0 - status: 2 - template: true - parameters: - lowTemperature: 64F - highTemperature: 71F - - - /admin/json/organizations/{organizationId}/challenges/{challengeId}: - put: - summary: Update a Challenge - operationId: Update a Challenge - description: >- - An administrator can modify all template fields except `template` and `challegeType`. - tags: - - Challenges - security: - - adminApiKey: [] - parameters: - - name: organizationId - in: path - description: Organization ID to update a challenge within - required: true - schema: - type: integer - - name: challengeId - in: path - description: Challenge ID to update - required: true - schema: - type: integer - requestBody: - content: - application/json: - example: - challenge: - name: DR event - startDate: '2014-08-01T00:00:00Z' - endDate: '2014-10-15T12:00:00Z' - schema: - type: object - properties: - challenge: - type: object - properties: - name: - type: string - startDate: - type: string - endDate: - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - delete: - summary: Delete a Challenge - operationId: Delete a Challenge - description: '' - tags: - - Challenges - security: - - adminApiKey: [] - parameters: - - name: organizationId - in: path - description: Organization ID - required: true - schema: - type: integer - - name: challengeId - in: path - description: Challenge ID to delete - required: true - schema: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /admin/json/organizations/{organizationId}/challenges/{challengeId}/status/{status}: - put: - summary: Update Challenge Status - operationId: Update Challenge Status - description: '' - tags: - - Challenges - security: - - adminApiKey: [] - parameters: - - name: organizationId - in: path - description: Organization ID to update - required: true - schema: - type: integer - - name: challengeId - in: path - description: Challenge ID to update - required: true - schema: - type: integer - - name: status - in: path - description: >- - New status
- 0 - Inactive challenge
- 1 - Active challenge - required: true - schema: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /admin/json/organizations/{organizationId}/challenges/{challengeId}/participants: - get: - summary: Get Participants - operationId: Get Participants - description: |- - Return invitational challenge participants. - - Only approved members of the given organization and the challenge participants can call this API. - - Participation statuses: - - | Status | Name | - | :----: | ---- | - | 1 | Not responded | - | 2 | Opt-In | - | 3 | Opt-Out | - tags: - - Challenges - security: - - userApiKey: [] - parameters: - - name: organizationId - in: path - description: Organization ID - required: true - schema: - type: integer - - name: challengeId - in: path - description: Challenge ID to obtain winners for - required: true - schema: - type: integer - - name: status - in: query - description: Participation status filter - schema: - type: integer - - name: locationId - in: query - description: Filter the response by location ID - schema: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - challenge: - type: object - properties: - locations: - type: array - items: - type: object - properties: - id: - type: string - locationName: - type: string - event: - type: string - participationStatus: - type: integer - participationUpdateDate: - type: string - participationUpdateDateMs: - type: integer - devices: - type: array - items: - type: object - properties: - id: - type: string - type: - type: integer - typeCategory: - type: integer - desc: - type: string - lastDataReceivedDate: - type: string - lastDataReceivedDateMs: - type: integer - example: - resultCode: 0 - challenge: - locations: - - id: '123' - locationName: John's home - event: Away - participationStatus: 2 - participationUpdateDate: '2014-09-09T17:36:20Z' - participationUpdateDateMs: 1410284180000 - devices: - - id: abc123 - type: 6 - typeCategory: 2 - desc: Living room Powerstrip - lastDataReceivedDate: '2015-06-27T02:14:00-04:00' - lastDataReceivedDateMs: 1435385640000 - - put: - summary: Update Status - operationId: Update Status - description: >- - Only approved members of the given organization and the challenge - participants can update their participation status to Opt-In or Opt-Out. - tags: - - Challenges - security: - - userApiKey: [] - parameters: - - name: organizationId - in: path - description: Organization ID - required: true - schema: - type: integer - - name: challengeId - in: path - description: Challenge ID to obtain winners for - required: true - schema: - type: integer - - name: status - in: query - description: New participation status - required: true - schema: - type: integer - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - /admin/json/organizations/{organizationId}/tags: get: summary: Popular Tags @@ -7589,6 +6991,4 @@ tags: - name: Firmware - - name: Challenges - - name: Status \ No newline at end of file diff --git a/docs/api/bots.yaml b/docs/api/bots.yaml index e2d9473..7cc9351 100644 --- a/docs/api/bots.yaml +++ b/docs/api/bots.yaml @@ -1,7 +1,7 @@ openapi: 3.1.1 info: title: 'IoT Software Suite: Bot API' - version: '63' + version: '65' description: |- The Bot Server is a real-time data analytics framework that allows software developers to create new bots, features, and services on top of any Internet-connected product. @@ -4024,7 +4024,6 @@ paths: type: integer required: - name - - index - value - time example: @@ -5557,6 +5556,10 @@ paths: type: string editable: type: boolean + permissions: + type: array + items: + type: integer question: type: object additionalProperties: @@ -5723,6 +5726,10 @@ paths: type: string locationId: type: integer + permissions: + type: array + items: + type: integer creationDateMs: type: integer responseType: @@ -6404,154 +6411,6 @@ paths: resultCode: 0 - /analytic/admin/challenges/{challengeId}/participants: - get: - summary: Get Participants - operationId: Get Participants - description: |- - Return invitational challenge participants. - - Participation statuses: - - | Status | Name | - |:------:|:--------------| - | 1 | Not responded | - | 2 | Opt-In | - | 3 | Opt-Out | - tags: - - Bot Challenge APIs - security: - - botApiKey: [] - parameters: - - name: challengeId - in: path - description: Challenge ID to obtain winners for - required: true - schema: - type: integer - - name: status - in: query - description: Participation status filter - schema: - type: integer - - name: locationId - in: query - description: Filter the response by location ID - schema: - type: integer - - name: getDevices - in: query - description: Return devices as well - schema: - type: boolean - - name: deviceCategory - in: query - description: Filter devices by a type category - schema: - type: integer - responses: - '200': - description: Challenge participants - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - locations: - type: array - items: - type: object - properties: - event: - type: string - id: - type: integer - timezone: - type: object - properties: - dst: - type: boolean - id: - type: string - name: - type: string - offset: - type: integer - participationStatus: - type: integer - participationUpdateDate: - type: string - participationUpdateDateMs: - type: integer - required: - - event - - id - - timezone - - participationStatus - - participationUpdateDate - - participationUpdateDateMs - example: - resultCode: 0 - locations: - - event: HOME - id: 1681 - timezone: - dst: true - id: America/Los_Angeles - name: Pacific Standard Time - offset: -480 - participationStatus: 2 - participationUpdateDate: '2017-05-06T03:29:26Z' - participationUpdateDateMs: 1494041366000 - - event: VACATION - id: 235379 - timezone: - dst: true - id: America/Adak - name: Hawaii Standard Time - offset: -600 - participationStatus: 2 - participationUpdateDate: '2017-05-06T03:29:26Z' - participationUpdateDateMs: 1494041366000 - - event: HOME - id: 235455 - timezone: - dst: false - id: Europe/Moscow - name: Moscow Standard Time - offset: 180 - participationStatus: 2 - participationUpdateDate: '2017-05-06T03:29:26Z' - participationUpdateDateMs: 1494041366000 - - event: HOME - id: 235681 - participationStatus: 2 - participationUpdateDate: '2017-05-06T03:29:26Z' - participationUpdateDateMs: 1494041366000 - - event: HOME - id: 236250 - timezone: - dst: true - id: America/New_York - name: Eastern Standard Time - offset: -300 - participationStatus: 2 - participationUpdateDate: '2017-05-06T03:29:26Z' - participationUpdateDateMs: 1494041366000 - - event: HOME - id: 236520 - timezone: - dst: true - id: America/Los_Angeles - name: Pacific Standard Time - offset: -480 - participationStatus: 2 - participationUpdateDate: '2017-05-06T03:29:26Z' - participationUpdateDateMs: 1494041366000 - - /deviceio/analytic: get: summary: Local Execution on a Computer @@ -6859,8 +6718,30 @@ paths: type: integer proxyId: type: string - modelId: - type: string + model: + type: object + properties: + modelId: + type: string + manufacturer: + type: object + displayInfo: + type: object + brands: + type: array + items: + type: object + properties: + brand: + type: string + name: + type: object + description: + type: object + parentId: + type: string + template: + type: string connected: type: boolean connectionStatus: @@ -6969,10 +6850,29 @@ paths: required: - deviceId - name - - index - value - time - updated + params: + type: array + description: Definitions of device parameters included to the measures + items: + type: object + properties: + paramName: + type: string + configured: + type: boolean + valueType: + type: integer + systemUnit: + type: string + systemMultiplier: + type: string + description: + type: string + displayInfo: + type: object alerts: type: array description: Device alerts @@ -6981,8 +6881,6 @@ paths: properties: deviceId: type: string - alertId: - type: integer alertType: type: string params: @@ -7190,6 +7088,53 @@ paths: type: string sliderUnit: type: string + escalation: + type: object + properties: + escalationId: + type: integer + escalationType: + type: integer + status: + type: integer + title: + type: string + description: + type: string + creationDateMs: + type: integer + expiryDateMs: + type: integer + eventDateMs: + type: integer + userId: + type: integer + description: Related event user ID + deviceId: + type: string + description: Triggering event device ID + eventSourceType: + type: integer + description: Triggering event source type + eventData: + type: object + description: Triggering event data except the device ID in flexible format + createBotService: + type: string + description: Bot service name, creating the excalation + confirmationDateMs: + type: integer + confirmUserId: + type: integer + description: User confirmed the event + resolutionDateMs: + type: integer + resolveUserId: + type: integer + description: User resolved the event + resolveSourceType: + type: integer + description: Data source type causing the exaclation resolution required: - time - trigger @@ -7246,7 +7191,14 @@ paths: deviceId: POWERSTRIP deviceType: 6 proxyId: GATEWAY_ID - modelId: PowerStrip + model: + modelId: PowerStrip + manufacturer: + en: Care Daily + brands: + - brand: default + name: + en: Power Strip connected: true description: Living room goalId: 20 @@ -7303,7 +7255,14 @@ paths: deviceId: POWERSTRIP deviceType: 6 proxyId: GATEWAY_ID - modelId: PowerStrip + model: + modelId: PowerStrip + manufacturer: + en: Care Daily + brands: + - brand: default + name: + en: Power Strip connected: true description: Living room goalId: 20 @@ -7397,7 +7356,14 @@ paths: deviceId: POWERSTRIP deviceType: 6 proxyId: GATEWAY_ID - modelId: PowerStrip + model: + modelId: PowerStrip + manufacturer: + en: Care Daily + brands: + - brand: default + name: + en: Power Strip connected: true description: Living room goalId: 20 @@ -7451,7 +7417,14 @@ paths: deviceId: POWERSTRIP deviceType: 6 proxyId: GATEWAY_ID - modelId: PowerStrip + model: + modelId: PowerStrip + manufacturer: + en: Care Daily + brands: + - brand: default + name: + en: Power Strip connected: true description: Living room goalId: 20 @@ -7702,22 +7675,23 @@ tags: A bot trigger is a bit mask, where each bit is related to specific functionality: - | Hex | Dec | Bit | Description | Details | - |:-----:|-----:|:---:|:-----------------------|:------- | - | 0x000 | 0 | | Reset | Execute the bot when a new instance created or it was inactive and then activated. | - | 0x001 | 1 | 0 | Schedule | Execute the bot based on a 'schedule'. | - | 0x002 | 2 | 1 | Location event | Execute the bot when the Location changes state, such as 'HOME', 'AWAY', etc.
The bot has to subscribe on this trigger value. | - | 0x004 | 4 | 2 | Device Alert | Execute the bot when the specified device sends an alert.
The bot has to subscribe on this trigger value. | - | 0x008 | 8 | 3 | Device Measurements | Execute the bot when the specified device receives a new measurement. You can optionally include a paramNameTrigger, and separately you can optionally include comma-separated parameter values to trigger on.
The bot has to subscribe on this trigger value. | - | 0x010 | 16 | 4 | Question answer | Execute the bot when a user answers a question. | - | 0x020 | 32 | 5 | Device Files | Execute the bot when a new file is uploaded by the device.
The bot has to subscribe on this trigger value. | - | 0x040 | 64 | 6 | Countdown Timer | The countdown timer can be requested by the bot to be executed in N seconds or at specified time. The bot must not specify it in own definition, but it will receive this trigger value in input data to indicate how it was triggered. | - | 0x080 | 128 | 7 | Device Configuration | Execute the bot when a device added, removed or configured.
The bot has to subscribe on this trigger value. | - | 0x100 | 256 | 8 | Data Stream | Bots, rules and other applications can send data to data stream.
The bot has to subscribe on specific data stream channel. | - | 0x200 | 512 | 9 | Survey Answers | An organization survey has been answered. | - | 0x400 | 1024 | 10 | Location Configuration | Execute the bot when a user or a space added or removed on a location.
The bot has to subscribe on this trigger value. | - | 0x800 | 2048 | 11 | Data request | Execute the bot when a data request completed. | - | 0x1000| 4096 | 12 | Messages | New messages created on a location or needs to be rescheduled. | + | Hex | Dec | Bit | Description | Details | + |:-----:|------:|:---:|:-----------------------|:------- | + | 0x000 | 0 | | Reset | Execute the bot when a new instance created or it was inactive and then activated. | + | 0x001 | 1 | 0 | Schedule | Execute the bot based on a 'schedule'. | + | 0x002 | 2 | 1 | Location event | Execute the bot when the Location changes state, such as 'HOME', 'AWAY', etc.
The bot has to subscribe on this trigger value. | + | 0x004 | 4 | 2 | Device Alert | Execute the bot when the specified device sends an alert.
The bot has to subscribe on this trigger value. | + | 0x008 | 8 | 3 | Device Measurements | Execute the bot when the specified device receives a new measurement. You can optionally include a paramNameTrigger, and separately you can optionally include comma-separated parameter values to trigger on.
The bot has to subscribe on this trigger value. | + | 0x010 | 16 | 4 | Question answer | Execute the bot when a user answers a question. | + | 0x020 | 32 | 5 | Device Files | Execute the bot when a new file is uploaded by the device.
The bot has to subscribe on this trigger value. | + | 0x040 | 64 | 6 | Countdown Timer | The countdown timer can be requested by the bot to be executed in N seconds or at specified time. The bot must not specify it in own definition, but it will receive this trigger value in input data to indicate how it was triggered. | + | 0x080 | 128 | 7 | Device Configuration | Execute the bot when a device added, removed or configured.
The bot has to subscribe on this trigger value. | + | 0x100 | 256 | 8 | Data Stream | Bots, rules and other applications can send data to data stream.
The bot has to subscribe on specific data stream channel. | + | 0x200 | 512 | 9 | Survey Answers | An organization survey has been answered. | + | 0x400 | 1024 | 10 | Location Configuration | Execute the bot when a user or a space added or removed on a location.
The bot has to subscribe on this trigger value. | + | 0x800 | 2048 | 11 | Data request | Execute the bot when a data request completed. | + | 0x1000| 4096 | 12 | Messages | New messages created on a location or needs to be rescheduled. | + | 0x4000| 16384 | 14 | Escalation | Updated escalation. | ### Access Resources @@ -7727,7 +7701,6 @@ tags: | 2 | Device files | | 3 | Professional monitoring call center | | 4 | Devices (in device types) | - | 5 | Challenges | | 6 | Rules | ### Communications @@ -7784,7 +7757,6 @@ tags: * [Delete Organization Object](admin.html#tag/Organizations/operation/Delete%20Object) * [Get Organization Users](admin.html#tag/Users-and-Locations/operation/Get%20Users) * [Get Organization Devices](admin.html#tag/Devices/operation/Get%20Devices) - * [Create a Challenge](admin.html#tag/Challenges/operation/Create%20a%20Challenge) - name: Bot Server APIs description: |- diff --git a/docs/api/cloud.yaml b/docs/api/cloud.yaml index ae14325..08211d7 100644 --- a/docs/api/cloud.yaml +++ b/docs/api/cloud.yaml @@ -1,7 +1,7 @@ openapi: 3.1.1 info: title: 'Care Daily AI and IoT Platform: Application API' - version: '63' + version: '65' description: |- The Care Daily AI and IoT Platform is the most comprehensive carrier-grade software suite ever developed for the creation and deployment of family-centric smart home and building services. The Care Daily AI Platform supports an AI Marketplace for 24/7 assistive services built with IoT devices, including coordination and communications between families and professionals. @@ -1436,7 +1436,6 @@ paths: phoneType: 1 appName: Care language: en - medicalRecordNumber: '12345' pronounId: 1 accessibility: 7 birthDate: 1950-12-31 @@ -1506,9 +1505,6 @@ paths: language: type: string description: Preferred language - medicalRecordNumber: - type: string - description: Medical Record Number pronounId: type: integer description: Pronoun ID. See the get pronouns API. @@ -1753,9 +1749,6 @@ paths: language: type: string description: User's preferred language. For example en - English, fr - French, ru - Russian, cn - Chinese, etc. - medicalRecordNumber: - type: string - description: Medical Record Number pronounId: type: integer description: User's pronoun ID. See the get pronouns API. @@ -1860,6 +1853,22 @@ paths: type: string externalId: type: string + description: Single partner's location ID + externalLocations: + type: array + description: Partner location identifiers + items: + type: object + properties: + applicationId: + type: integer + description: Partner cloud ID + locationType: + type: integer + description: 0 - default, 1 - apartment + externalLocationId: + type: string + description: Partner's ID locationUser: type: object properties: @@ -1957,8 +1966,6 @@ paths: type: string priorityDateMs: type: integer - codeType: - type: integer event: type: string startDate: @@ -2012,8 +2019,6 @@ paths: type: string amount: type: integer - resourceType: - type: integer startDate: type: string startDateMs: @@ -2026,7 +2031,6 @@ paths: - name - desc - amount - - resourceType - startDate - startDateMs - endDate @@ -2129,7 +2133,6 @@ paths: priorityComment: Short note here priorityDate: '2019-01-29T02:45:30Z' priorityDateMs: 1548747995000 - codeType: 1 event: HOME size: unit: ft2 @@ -2162,7 +2165,6 @@ paths: - name: Family desc: Care Daily Family service amount: 1 - resourceType: 1 startDate: '2014-05-01T12:00:00Z' startDateMs: 1398945600000 endDate: '2014-06-01T12:00:00Z' @@ -2170,7 +2172,6 @@ paths: - name: DeviceFileSpace desc: Files storage space amount: 7 - resourceType: 1 startDate: '2014-05-01T12:00:00Z' startDateMs: 1398945600000 endDate: '2014-06-01T12:00:00Z' @@ -2245,9 +2246,6 @@ paths: type: integer language: type: string - medicalRecordNumber: - type: string - description: Medical Record Number pronounId: type: integer accessibility: @@ -2717,138 +2715,6 @@ paths: resultCode: 0 - /cloud/json/userCodes: - put: - summary: Put User Code - operationId: Put User Code - description: |- - This API allows to add a new or overwrite an existing user's code or update a shared code on the location. - A user's code can be set by either providing the actual code value or by initiating a process entering the code on the device. - If the user's code is set by the device (type 4), process expiry time in seconds can be provided in the `setExpiry` field. - - | Type | Description | - | :--: | ----------- | - | 1 | Manual | - | 2 | Card | - | 3 | Combined | - | 4 | From device | - tags: - - User Accounts - security: - - userApiKey: [] - parameters: - - name: name - in: query - description: Code name required for user codes - schema: - type: string - - name: locationId - in: query - description: Location ID for the location's code - schema: - type: string - requestBody: - content: - application/json: - example: - type: 1 - code: '123456' - deviceId: ABC123 - setExpiry: 60 - verify: true - schema: - type: object - properties: - type: - type: integer - code: - type: string - deviceId: - type: string - setExpiry: - type: integer - verify: - type: boolean - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - delete: - summary: Delete User Code - operationId: Delete User Code - tags: - - User Accounts - security: - - userApiKey: [] - parameters: - - name: name - in: query - description: Code name required for user codes - schema: - type: string - - name: locationId - in: query - description: Location ID for the location's code - schema: - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - get: - summary: Get User Codes - operationId: Get User Codes - tags: - - User Accounts - security: - - userApiKey: [] - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - codes: - type: array - items: - type: object - properties: - type: - type: integer - verified: - type: boolean - name: - type: string - example: - resultCode: 0 - codes: - - type: 1 - verified: true - name: My code - - /cloud/json/location: post: summary: Create Location @@ -3118,148 +2984,6 @@ paths: resultCode: 0 - /cloud/json/location/{locationId}/event/{eventName}: - post: - summary: Change the Scene at a Location - operationId: Change the Scene at a Location - description: >- - By changing the scene at a location, you may cause AI logic to execute such as "When I am home do something" or "When I am going to sleep turn off the TV". - tags: - - Locations - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: locationId - in: path - description: The Location ID for which to trigger an event - required: true - schema: - type: integer - - name: eventName - in: path - description: >- - Developer-defined name of the scene. For example, 'HOME', 'AWAY', 'SLEEP', 'VACATION', 'FOOSBALL'. - You can define any name you want. - The name represents some state, and can be fed into Rules and other areas of the app. - required: true - schema: - type: string - requestBody: - content: - application/json: - example: - comment: Optional, why this event sent - schema: - type: object - properties: - comment: - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/json/location/{locationId}/events: - get: - summary: Location Scenes History - operationId: Location Scenes History - description: |- - Return location change schemes history in backward order (latest first). - - Source types: - - | Type | Description | - | :--: | ----------- | - | 0 | User app | - | 1 | Rule | - | 2 | Bot | - | 9 | Third-party OAuth client | - tags: - - Locations - security: - - userApiKey: [] - parameters: - - name: locationId - in: path - description: The Location ID - required: true - schema: - type: integer - - name: startDate - in: query - description: Start date to begin receiving data - schema: - type: string - - name: endDate - in: query - description: End date to stop receiving data. Default is the current date. - schema: - type: string - responses: - '200': - description: Location Scenes - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - events: - type: array - items: - type: object - properties: - event: - type: string - description: Scene value - eventDate: - type: string - description: Scene date - eventDateMs: - type: integer - sourceType: - type: integer - description: Client's type which set the scene - sourceAgent: - type: string - description: HTTP User-Agent header value - comment: - type: string - required: - - event - - eventDate - - eventDateMs - example: - resultCode: 0 - events: - - event: HOME - eventDate: '2015-10-01T18:00:00Z' - eventDateMs: 1443722400000 - sourceType: 0 - sourceAgent: Care/4.0.19 (iPhone; iOS 10.3.3; Scale/2.00) - - event: AWAY - eventDate: '2015-09-15T18:00:00Z' - eventDateMs: 1442340000000 - sourceType: 1 - comment: Did not detect motions for one hour - - event: HOME - eventDate: '2015-09-01T18:00:00Z' - eventDateMs: 1441130400000 - sourceType: 2 - comment: Recognized a tenant - - /cloud/json/location/{locationId}/priorities: get: summary: Location Priorities History @@ -3721,9 +3445,6 @@ paths: description: System user's role language: type: string - medicalRecordNumber: - type: string - description: Medical Record Number accessibility: type: integer birthDate: @@ -4128,8 +3849,6 @@ paths: type: string priorityDateMs: type: integer - codeType: - type: integer event: type: string test: @@ -4295,138 +4014,42 @@ paths: resultCode: 0 - /cloud/json/locations/{locationId}/narratives: - put: - summary: Create or Update a Narrative - operationId: Create or Update a Narrative - description: |- - Narratives are time-series auditable records that log human-readable events from a location. - They are typically used to enable Explainable AI, and record exactly what happened at what time in a home or business. - Narratives can include arbitrary JSON content underneath the human-visible layer to enable debugging and analytics. - - Friends and family who can switch into and view your location should be able to see your narrative. - - Administrators should also be able to access your narrative in Maestro for debugging / understanding / explanation of "why did that happen in my home?" purposes. - - | Status | Description | - | :----: | ----------- | - | 0 | Default initial | - | 1 | Deleted | - | ... | Any other value | - - | Type | Description | - | :--: | ----------- | - | 0 | High-frequency time-series "observations", default | - | 1 | Deleted user (organization) | - | 2 | Deleted location (organization) | - | 3 | Moved location (organization) | - | 4 | Low-frequency time-series "journal" | - | 5 | Insight | - | 6 | Support Ticket | - - Narrative time is always truncated to seconds by the API. - - When a new narrative is created, the API returns the new record ID and `narrativeTime` in milliseconds. - - To update an existing narrative record both `narrativeId` and `narrativeTime` query parameters must be provided. - The new value of `narrativeTime` in milliseconds will be returned, if it has been changed. + /cloud/json/locationTotals: + get: + summary: Get Totals + operationId: Get Totals + description: >- + For the location landing page we are displaying the location's total files, devices and rules. + This is a single API to request total numbers. tags: - Locations security: - userApiKey: [] - - botApiKey: [] parameters: - name: locationId - in: path - description: Location ID - required: true - schema: - type: integer - - name: scope in: query - description: Scope:
1 = location,
2 = organization + description: Location ID required: true schema: type: integer - enum: [1,2] - - name: publish + - name: devices in: query - description: Publish narrative to subscribers, default is true + description: Return total devices number schema: type: boolean - - name: store + - name: files in: query - description: |- - Store a new narrative in the database, default is true.
- Can be set to `false`, if it is only for publishing. + description: Return total files number schema: type: boolean - - name: narrativeId - in: query - description: ID of narrative for update - schema: - type: integer - - name: narrativeTime + - name: rules in: query - description: narrative time as returned from the API for update + description: Return total rules number schema: - type: integer - requestBody: - content: - application/json: - example: - narrative: - narrativeTime: 1537692964000 - priority: 1 - status: 0 - narrativeType: 0 - eventType: thermostat - icon: icon.gif - iconFont: icon.font - title: Water Leak - description: Water leak in the bathroom - target: - fileIDs: - - 1234 - - 2366 - field: value - schema: - type: object - properties: - narrative: - type: object - properties: - narrativeTime: - type: integer - description: Narrative time in milliseconds for a new record - parentId: - type: integer - description: Parent narrative ID - parentNarrativeTime: - type: integer - description: Parent narrative time in milliseconds - priority: - type: integer - status: - type: integer - narrativeType: - type: integer - eventType: - type: string - icon: - type: string - iconFont: - type: string - title: - type: string - description: - type: string - target: - type: object - description: Flexible sructure object + type: boolean responses: '200': - description: New narrative ID + description: OK content: application/json: schema: @@ -4434,112 +4057,143 @@ paths: properties: resultCode: type: integer - narrativeId: + devicesTotal: type: integer - narrativeTime: + filesTotal: + type: integer + rulesTotal: type: integer example: resultCode: 0 - narrativeId: 123 - narrativeTime: 1537692964000 + devicesTotal: 3 + filesTotal: 50 + rulesTotal: 10 - get: - summary: Get Narratives - operationId: Get Narratives - description: |- - The search results are organized by "pages". - Each page contains a set of elements sorted by the `narrativeTime` in descending order. - The pages follow one another in reverse chronological order. - The rowCount parameter specifies the maximum number of elements per page. - The result may include the `nextMarker` property - this means that there are more pages for the current search criteria. - To get the next page, the value of `nextMarker` must be passed to the `pageMarker` parameter on the next API call. + /cloud/appstore/summary: + get: + summary: Get Summary + operationId: Get Summary + description: Returns a list of microservices and data stream addresses for a specified location or bots running within an organization. tags: - - Locations + - Location Events security: - userApiKey: [] - - botApiKey: [] parameters: - name: locationId - in: path - description: Location ID - required: true - schema: - type: integer - - name: rowCount - in: query - description: Maximum number of elements per page - schema: - type: integer - - name: narrativeId - in: query - description: Filter by ID - schema: - type: integer - - name: narrativeTime - in: query - description: Specific narrative time - schema: - type: integer - - name: parentId in: query - description: Filter by parent ID + description: Location ID schema: type: integer - - name: narrativeType + - name: organizationId in: query - description: Filter by narrative type, multiple values + description: Organization ID schema: type: integer + responses: + '200': + description: Summary + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + dataStreams: + type: array + items: + type: string + microServices: + type: array + items: + type: string + example: + resultCode: 0 + dataStreams: + - address1 + - address2 + microServices: + - sms_invite + - email_invite + - in_app_invite + + + /cloud/appstore/stream: + post: + summary: Stream message + operationId: Stream message + description: |- + Applications can send data messages to bots. These messages are transient. + They're not stored or logged, but bots can choose to record them in the history by using Narratives. + + The message can be sent to bots that are subscribed on the specific data stream address, or bots of specific instance ID's. + + End users can send messages to bots that only purchased by them, or organizational bots that operate above their location. + + Organization administrators can send messages to organizational bots in the same organization, and to non-organization and individual bots of users within this organization. + + The end user IDs and the bot IDs (appInstanceId) are specified in the request body. + tags: + - Location Events + security: + - userApiKey: [] + parameters: - name: scope in: query - description: Scope:
1 = location, default,
2 = organization, for bots only + description: |- + Bitmask to feed organizational and location bots: +
1 - individual +
2 - organizational + required: true schema: type: integer - enum: [1,2] - - name: priority + - name: address in: query - description: Filter by priority higher or equal than that + description: Data stream address + required: true schema: - type: integer - - name: toPriority + type: string + - name: locationId in: query - description: Filter by priority less or equal than that + description: Send data to bots of this location. Mandatory for end users. schema: type: integer - - name: status + - name: organizationId in: query - description: Filter by status, deleted are not returned by default + description: Send data to bots of users of the specific organization, used by an administrator schema: type: integer - - name: eventType - in: query - description: Filter by event type - schema: - type: string - - name: searchBy - in: query - description: Filter by title or description. Use * for a wildcard. - schema: - type: string - - name: startDate - in: query - description: Narrative date range start - schema: - type: string - - name: endDate - in: query - description: Narrative date range end - schema: - type: string - - name: pageMarker - in: query - description: Marker to the next page - schema: - type: string + requestBody: + content: + application/json: + example: + locations: + - 34122 + - 15689 + bots: + - 567 + - 893 + feed: + key0: value0 + key1: value1 + schema: + type: object + properties: + locations: + type: array + items: + type: integer + bots: + type: array + items: + type: integer + feed: + type: object + description: Flexible structure object responses: '200': - description: Narratives + description: OK content: application/json: schema: @@ -4547,99 +4201,27 @@ paths: properties: resultCode: type: integer - nextMarker: - type: string - description: Pass it to the `pageMarker` parameter on the next API call - narratives: - type: array - items: - type: object - properties: - id: - type: integer - locationId: - type: integer - narrativeDate: - type: string - narrativeDateMs: - type: integer - creationDate: - type: string - creationDateMs: - type: integer - narrativeType: - type: integer - priority: - type: integer - status: - type: integer - icon: - type: string - title: - type: string - description: - type: string - target: - type: object - description: Flexible structure object - appInstanceId: - type: integer - description: Bot instance ID, which created this record - iconFont: - type: string - required: - - id - - locationId - - narrativeDate - - narrativeDateMs - - creationDate - - creationDateMs - - narrativeType - - priority - - status example: resultCode: 0 - nextMarker: 16611d93630-306b - narratives: - - id: 20 - locationId: 1 - narrativeDate: '2018-10-01T03:05:07' - narrativeDateMs: 1537692964000 - creationDate: '2018-10-01T03:05:07' - creationDateMs: 1537692964000 - narrativeType: 0 - priority: 3 - status: 0 - icon: alert.gif - title: Water Leak - description: Water leak in the bathroom - target: - field: value - appInstanceId: 520 - - id: 19 - locationId: 1 - narrativeDate: '2018-10-01T03:05:07' - narrativeDateMs: 1537692964000 - creationDate: '2018-10-01T03:05:07' - creationDateMs: 1537692964000 - narrativeType: 0 - priority: 1 - status: 2 - icon: icon4 - iconFont: icon.font - title: Left the house - description: Left the house - target: - field: value - appInstanceId: 520 - delete: - summary: Delete a Narrative - operationId: Delete a Narrative - description: '' + + /cloud/json/locations/{locationId}/state: + put: + summary: Set Location State + operationId: Set Location State + description: |- + Location states are a way for bots and users to set named location states with flexible object structure. + + The location state value can be an any valid JSON node. + It can be a single value node (string, integer, etc.) or an array or an object node `{}`. + If the value is an object node, the API will read the current state value and try to update only changed fields. + + To remove a state, set the value to `null`. + To delete a field from the current value set it to `null`. tags: - - Locations + - Location Events security: + - userApiKey: [] - botApiKey: [] parameters: - name: locationId @@ -4648,35 +4230,54 @@ paths: required: true schema: type: integer - - name: scope - in: query - description: Scope:
1 = location,
2 = organization - required: true - schema: - type: integer - enum: [1,2] - - name: narrativeId + - name: name in: query - description: ID of narrative to delete + description: State name required: true schema: - type: integer - - name: narrativeTime + type: string + - name: overwrite in: query - description: narrative time in milliseconds - required: true + description: Overwrite the entire state with completely new content schema: - type: integer + type: boolean - name: publish in: query - description: Publish narrative to subscribers, default is true + description: Publish state to subscribers, default is true schema: type: boolean - - name: eventType + - name: upd in: query - description: Publishing event type + description: >- + Array of updated or added top level properties of the state. +
Used with overwrite=true to inform a partner's cloud. + schema: + type: string + - name: del + in: query + description: >- + Array of deleted top level properties of the state. +
Used to inform a partner's cloud. schema: type: string + requestBody: + content: + application/json: + example: + value: + field0: 123 + field1: + ids: + - 1234 + - 2366 + key: value + fieldToDelete: null + schema: + type: object + properties: + value: + type: object + description: Flexible structure object responses: '200': description: OK @@ -4690,43 +4291,30 @@ paths: example: resultCode: 0 - - /cloud/json/locationTotals: get: - summary: Get Totals - operationId: Get Totals - description: >- - For the location landing page we are displaying the location's total files, devices and rules. - This is a single API to request total numbers. + summary: Get Location State + operationId: Get Location State tags: - - Locations + - Location Events security: - userApiKey: [] + - botApiKey: [] parameters: - name: locationId - in: query + in: path description: Location ID required: true schema: type: integer - - name: devices - in: query - description: Return total devices number - schema: - type: boolean - - name: files - in: query - description: Return total files number - schema: - type: boolean - - name: rules + - name: name in: query - description: Return total rules number + description: State name(s), multiple values supported + required: true schema: - type: boolean + type: string responses: '200': - description: OK + description: State(s) content: application/json: schema: @@ -4734,276 +4322,9 @@ paths: properties: resultCode: type: integer - devicesTotal: - type: integer - filesTotal: - type: integer - rulesTotal: - type: integer - example: - resultCode: 0 - devicesTotal: 3 - filesTotal: 50 - rulesTotal: 10 - - - /cloud/appstore/stream: - post: - summary: Stream message - operationId: Stream message - description: |- - Applications can send data messages to bots. These messages are transient. - They're not stored or logged, but bots can choose to record them in the history by using Narratives. - - The message can be sent to bots that are subscribed on the specific data stream address, or bots of specific instance ID's. - - End users can send messages to bots that only purchased by them, or organizational bots that operate above their location. - - Organization administrators can send messages to organizational bots in the same organization, and to non-organization and individual bots of users within this organization. - - The end user IDs and the bot IDs (appInstanceId) are specified in the request body. - tags: - - Synthetic APIs - security: - - userApiKey: [] - parameters: - - name: scope - in: query - description: |- - Bitmask to feed organizational and location bots: -
1 - individual -
2 - organizational - required: true - schema: - type: integer - - name: address - in: query - description: Data stream address - required: true - schema: - type: string - - name: locationId - in: query - description: Send data to bots of this location. Mandatory for end users. - schema: - type: integer - - name: organizationId - in: query - description: Send data to bots of users of the specific organization, used by an administrator - schema: - type: integer - requestBody: - content: - application/json: - example: - locations: - - 34122 - - 15689 - bots: - - 567 - - 893 - feed: - key0: value0 - key1: value1 - schema: - type: object - properties: - locations: - type: array - items: - type: integer - bots: - type: array - items: - type: integer - feed: - type: object - description: Flexible structure object - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/appstore/summary: - get: - summary: Get Summary - operationId: Get Summary - description: Returns a list of microservices and data stream addresses for a specified location or bots running within an organization. - tags: - - Synthetic APIs - security: - - userApiKey: [] - parameters: - - name: locationId - in: query - description: Location ID - schema: - type: integer - - name: organizationId - in: query - description: Organization ID - schema: - type: integer - responses: - '200': - description: Summary - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - dataStreams: - type: array - items: - type: string - microServices: - type: array - items: - type: string - example: - resultCode: 0 - dataStreams: - - address1 - - address2 - microServices: - - sms_invite - - email_invite - - in_app_invite - - - /cloud/json/locations/{locationId}/state: - put: - summary: Set Location State - operationId: Set Location State - description: |- - Location state variables are a way for bots and users to set named location states with flexible object structure. - - The location state value can be an any valid JSON node. - When a state variable is saved by a bot, its contents will persist in the location beyond the lifetime of the bot. - It can be a single value node (string, integer, etc.) or an array or an object node `{}`. - - If the value is an object node, the API will read the current state value and try to update only changed fields. - - To remove a state, set the value to `null`. - To delete a field from the current value set it to `null`. - tags: - - Synthetic APIs - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: locationId - in: path - description: Location ID - required: true - schema: - type: integer - - name: name - in: query - description: State name - required: true - schema: - type: string - - name: overwrite - in: query - description: Overwrite the entire state with completely new content - schema: - type: boolean - - name: publish - in: query - description: Publish state to subscribers, default is true - schema: - type: boolean - - name: upd - in: query - description: >- - Array of updated or added top level properties of the state. -
Used with overwrite=true to inform a partner's cloud. - schema: - type: string - - name: del - in: query - description: >- - Array of deleted top level properties of the state. -
Used to inform a partner's cloud. - schema: - type: string - requestBody: - content: - application/json: - example: - value: - field0: 123 - field1: - ids: - - 1234 - - 2366 - key: value - fieldToDelete: null - schema: - type: object - properties: - value: - type: object - description: Flexible structure object - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - get: - summary: Get Location State - operationId: Get Location State - tags: - - Synthetic APIs - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: locationId - in: path - description: Location ID - required: true - schema: - type: integer - - name: name - in: query - description: State name(s), multiple values supported - required: true - schema: - type: string - responses: - '200': - description: State(s) - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - stateDate: - type: string - stateDateMs: + stateDate: + type: string + stateDateMs: type: integer value: type: object @@ -5044,7 +4365,7 @@ paths: operationId: Delete All Location States description: Delete all states on the location tags: - - Synthetic APIs + - Location Events security: - userApiKey: [] parameters: @@ -5076,13 +4397,12 @@ paths: Time-series location states are a way for bots and users to capture time-series addressable state information with flexible object structure. The state value can be an any valid JSON node. It can be a single value node (string, integer, etc.) or an array or an object node `{}`. - If the value is an object node, the API will read the current state value and try to update only changed fields. To delete a location state set the value to `null`. To delete a field from the current value, set it to `null`. tags: - - Synthetic APIs + - Location Events security: - userApiKey: [] - botApiKey: [] @@ -5159,7 +4479,7 @@ paths: summary: Get Location Time-series States operationId: Get Location Time-series States tags: - - Synthetic APIs + - Location Events security: - userApiKey: [] - botApiKey: [] @@ -5256,41 +4576,79 @@ paths: count: 10 - /clouse/json/openai: + /cloud/json/escalations: post: - summary: Send a request to OpenAI - operationId: Send a request to OpenAI + summary: Create Escalation + operationId: Create Escalation description: |- - Send a synchronous request to OpenAI API to obtain a model response for the given chat conversation. + Escalations are significant events captured inside Care Daily platform and created by bots. + For examples, a fall, an emergency request, a device outage, "not back home". + Escalations can be reactions to device parameters change or captured from external data-streaming resources. - The response from CharGPT is returned by the API and can look like: - - > - { - "id" : "chatcmpl-86GKbsl3bP5YmmxutIY8aS5c5o5gK", - "object" : "chat.completion", - "created" : 1696503437, - "model" : "gpt-3.5-turbo-0613", - "choices" : [ - { - "index" : 0, - "message" : { - "role" : "assistant", - "content" : "This is a test!" - }, - "finish_reason" : "stop" - } - ], - "usage" : { - "prompt_tokens" : 13, - "completion_tokens" : 5, - "total_tokens" : 18 - } - } + An escalation can be referenced in following narratives, notifications, tickets. + + **Escalation Statuses** + + | Status | Name | + | :----: | ---- | + | 1 | Open | + | 2 | Confirmed | + | 3 | Resolved | + | 4 | Cancelled (including false positive) | + | 5 | Expired | + + **Escalation Types** + + | Type | Description | + | :--: | ----------- | + | | ***Care*** | + | 1 | Fall detected | + | 2 | Fall risk | + | 3 | Call for help | + | 4 | Did not wake up | + | 5 | Inactivity | + | 6 | Sleep interruption | + | 7 | Not back home | + | 8 | Wandering | + | 9 | Health alert | + | 19 | Out of bed too long | + | 20 | Didn't come to bed | + | 21 | Bed Exit | + | | ***Security and hazards*** | + | 10 | Security alarm | + | 11 | Duress | + | 12 | Smoke | + | 13 | Water leak | + | 14 | Stove hazard | + | | ***Technical*** | + | 15 | Proxy/gateway offline | + | 16 | Device offline | + | 17 | Low battery | + | 18 | Unstable connection | + + **Priorities** + + | Priority | Description | + | :------: | ----------- | + | 1 | Normal | + | 2 | High | + | 3 | Urgent | + + **Possible Source Types** + + | Source | Description | + | :----: | ----------- | + | 0 | End User | + | 2 | Bot Logic | + | 6 | System Logic | + | 7 | External Application | + | 8 | Device Data | + | 10 | Staff | + | 11 | Administrator | tags: - - Synthetic APIs + - Location Events security: - - userApiKey: [] + - botApiKey: [] parameters: - name: locationId in: query @@ -5298,35 +4656,62 @@ paths: required: true schema: type: integer - - name: openAiOrganization - in: query - description: An organization which will be used (charged) for an Open AI API request. - schema: - type: string - - name: openAiPath - in: query - description: |- - A path index which will be used for an Open AI API request.
- Available values are
- 0 - /v1/chat/completions,
- 1 - /v1/responses. - required: true - schema: - type: integer requestBody: content: application/json: + schema: + type: object + properties: + escalation: + type: object + properties: + escalationType: + type: integer + title: + type: string + description: + type: string + priority: + type: integer + icon: + type: string + expiryDate: + type: string + description: Excalation expiry date + eventDate: + type: string + description: Triggering event date and time + userId: + type: integer + description: Related event user ID + deviceId: + type: string + description: Triggering event device ID + eventSourceType: + type: integer + description: Triggering event source type + eventData: + type: object + description: Triggering event data except the device ID in flexible format + createBotService: + type: string + description: Bot service name, creating the excalation + required: + - escalationType + - priority example: - answer: - model: gpt-5 - input: Some text for the Responses API - messages: - - content: Some text for the Chat Completions API - role: user - temperature: 0.7 + escalation: + escalationType: 1 + userId: 123 + title: Fall + description: Resident fall detected + eventDate: 2026-09-10T14:05:23Z + deviceId: abc123 + eventSourceType: 1 + createBotService: fall.service responses: '200': - description: OpenAI response + description: OK content: application/json: schema: @@ -5334,21 +4719,21 @@ paths: properties: resultCode: type: integer - answer: - type: object + escalationId: + type: integer example: resultCode: 0 + escalationId: 456 - - /clouse/json/openaiToken: - get: - summary: Get OpenAI client token - operationId: Get OpenAI client token + put: + summary: Update Escalation + operationId: Update Escalation description: |- - Send a synchronous request to OpenAI API to retrieve an ephemeral token. + Update an escalation status and related fields tags: - - Synthetic APIs + - Location Events security: + - botApiKey: [] - userApiKey: [] parameters: - name: locationId @@ -5357,15 +4742,47 @@ paths: required: true schema: type: integer - - name: expiry + - name: escalationId in: query - description: An optional expiry in seconds + description: Escalation ID required: true schema: type: integer + requestBody: + content: + application/json: + schema: + type: object + properties: + escalation: + type: object + properties: + status: + type: integer + confirmationDate: + type: string + description: When an event has been confirmed. Will be set to the current time by default for the confirmation status. + confirmUserId: + type: integer + description: User confirmed the event + resolutionDate: + type: string + description: When an exaclation resolved. Will be set to the current time by default for closing statuses. + resolveUserId: + type: integer + description: User resolved the event + resolveSourceType: + type: integer + description: Data source type causing the exaclation resolution + example: + escalation: + status: 3 + resolutionDate: 2026-09-10T14:05:23Z + resolveUserId: 123 + resolveSourceType: 1 responses: '200': - description: OpenAI response + description: OK content: application/json: schema: @@ -5373,138 +4790,63 @@ paths: properties: resultCode: type: integer - answer: - type: object example: resultCode: 0 - - /cloud/json/devices: - post: - summary: Register a Device - operationId: Register a Device + get: + summary: Get Escalations + operationId: Get Escalations description: |- - Registration response will describe how the device should connect to the cloud server instance. - - - - - - - - - - - - - - - -
NameDescriptionDetails
deviceIdstringDevice IDs are globally unique, must be 50 or less characters long, and must not contain '/', '%', '#', or '+' characters.
authTokenbooleanStandard SSL only supports one-way authentication. - The Care Daily AI Platform takes security a leap forward by allowing the use of an optional cryptographic authentication token to be used for bi-directional authentication of a device. - If requested, your device will be responsible for securely storing the generated authentication token and including it in all future HTTP requests to the Care Daily AI Platform.
- true - Request an authentication token
- false - Do not use an authentication token
startDateIn milliseconds or ISO 8601The absolute date timestamp when the device is registered to the user's account. - The Care Daily AI Platform will not store any data from a device before its registration time. - For example, if you have historical data from this device that you want associated with the user's account, - then the registration time should be set in the past to be able to store all that historical data. - The default start time is the current time on the server.
+ Select escalations by search parameters tags: - - Devices + - Location Events security: + - botApiKey: [] - userApiKey: [] parameters: - - name: deviceId - in: query - description: Globally unique device identifier for this device. Must not include '/', '%', '#', or '+' characters. - schema: - type: string - name: locationId in: query - description: The Location to add this device to. Mandatory when called by a user. + description: Location ID. Required for end-users or if the `organizationId` parameter not provided. schema: type: integer - - name: proxyId - in: query - description: Send the add device command to this proxy - schema: - type: string - - name: deviceType + - name: organizationId in: query - description: Type of the device being registered. Optional, but highly recommended you specify this. + description: Organization ID. For admins only. Required if the `locationId` parameter not provided. schema: type: integer - - name: authToken + - name: escalationId in: query - description: |- - true - Request an authentication token -
false - No authentication token necessary + description: Escalation ID schema: - type: boolean + type: integer - name: startDate in: query - description: |- - Timestamp at which to register this device. -
The Care Daily AI Platform will ignore inbound measurements with a timestamp before the registration time. -
Default is the current time. + description: Search start date and time. Required if the `escalationId` parameter not provided. schema: type: string - - name: desc + - name: endDate in: query - description: Device nickname / description + description: Search end date and time schema: type: string - - name: goalId + - name: status in: query - description: Device usage goal ID + description: Escalation statuses. Multiple values supported. schema: type: integer - - name: modelId + - name: escalationType in: query - description: Device model ID + description: Escalation types. Multiple values supported. schema: type: integer - - name: userId + - name: priority in: query - description: User ID associated with a personal device + description: Priorities. Multiple values supported. schema: type: integer - - name: ACTIVATION_KEY - in: header - description: Device activation key, if the API key is not provided - schema: - type: string - requestBody: - content: - application/json: - example: - properties: - - name: username - value: admin - - name: port - index: '01' - value: '1234' - schema: - type: object - properties: - properties: - type: array - description: Name/value properties - items: - type: object - properties: - name: - type: string - value: - type: string - index: - type: string - required: - - name - - value responses: '200': - description: Device regisration result + description: Escalations content: application/json: schema: @@ -5512,95 +4854,241 @@ paths: properties: resultCode: type: integer - deviceId: - type: string - authToken: - type: string - deviceType: - type: integer - locationId: - type: integer - exist: - type: boolean - config: - type: object - description: Flexible structure object depending on the device type for device provisioning and initial configuration - host: - type: string - port: - type: integer - useSSL: - type: boolean - example: - resultCode: 0 - deviceId: globally-unique-device-id - authToken: generated device authentication token - deviceType: 123 - locationId: 456 - exist: false - host: esp.peoplepowerco.com - port: 8443 - useSSL: true - - get: - summary: Get Devices - operationId: Get Devices - description: |- - Returns a list of devices belonging to the location. - Also this API returns some UI specific device type attributes and device parameters. - - | Simulated | Description | - | :-------: | ----------- | - | -1 | Real device which data copied to simulated devices | - | 1 | Device data simulated by the cloud scheduler | - | 2 | Device data copied from a real device | - | 3 | Device data simulated by a "flexible" simulator | - tags: - - Devices - security: - - userApiKey: [] - parameters: - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - - name: spaceId - in: query - description: Filter devices by space ID - schema: - type: integer - - name: spaceType - in: query - description: Filter devices by space type + escalations: + type: array + items: + type: object + properties: + escalationId: + type: integer + locationId: + type: integer + escalationType: + type: integer + status: + type: integer + title: + type: string + description: + type: string + priority: + type: integer + icon: + type: string + creationDate: + type: string + creationDateMs: + type: integer + expiryDate: + type: string + description: Excalation expiry date + expiryDateMs: + type: integer + eventDate: + type: string + description: Triggering event date and time + eventDateMs: + type: integer + userId: + type: integer + description: Related event user ID + deviceId: + type: string + description: Triggering event device ID + device: + type: object + properties: + id: + type: string + description: Device ID + type: + type: integer + description: Device Type + goalId: + type: integer + description: Device usage goal ID + locationId: + type: integer + description: Device location ID + userId: + type: integer + description: Device user ID + desc: + type: string + description: Device name or description + connected: + type: boolean + description: Device connection status + modelId: + type: string + description: Device model ID + lastDataReceivedDate: + type: string + description: Last time, when any data received for this device + lastDataReceivedDateMs: + type: integer + lastMeasureDate: + type: string + description: Last time, when device measurements received + lastMeasureDateMs: + type: integer + proxyId: + type: string + description: Device proxy or hub ID + zoneId: + type: string + description: Device zone ID + applicationId: + type: integer + description: Device integration cloud ID + authId: + type: string + description: Device integration authentication ID + eventSourceType: + type: integer + description: Triggering event source type + eventData: + type: object + description: Triggering event data except the device ID in flexible format + createBotInstanceId: + type: integer + description: Bot instance created the escalation + createBotService: + type: string + description: Bot service name, creating the excalation + confirmationDate: + type: string + description: When an event has been confirmed. Will be set to the current time by default for the confirmation status. + confirmationDateMs: + type: integer + confirmUserId: + type: integer + description: User confirmed the event + resolutionDate: + type: string + description: When an exaclation resolved. Will be set to the current time by default for closing statuses. + resolutionDateMs: + type: integer + resolveUserId: + type: integer + description: User resolved the event + resolveSourceType: + type: integer + description: Data source type causing the exaclation resolution + example: + resultCode: 0 + escalations: + - escalationId: 456 + locationId: 123 + escalationType: 1 + status: 3 + title: Fall + description: Resident fall detected + creationDate: '2026-09-10T10:05:23-04:00' + creationDateMs: 1757513123000 + eventDate: '2026-09-10T10:05:23-04:00' + eventDateMs: 1757513123000 + userId: 123 + deviceId: abc123 + eventSourceType: 1 + createBotInstanceId: 789 + createBotService: fall.service + resolutionDate: '2026-09-10T10:15:00-04:00' + resolutionDateMs: 1757513700000 + resolveUserId: 123 + resolveSourceType: 1 + + + /cloud/json/location/{locationId}/event/{eventName}: + post: + summary: Change the Scene at a Location + operationId: Change the Scene at a Location + description: >- + By changing the scene at a location, you may cause AI logic to execute such as "When I am home do something" or "When I am going to sleep turn off the TV". + tags: + - Location Events + security: + - userApiKey: [] + - botApiKey: [] + parameters: + - name: locationId + in: path + description: The Location ID for which to trigger an event + required: true schema: type: integer - - name: checkPersistent - in: query + - name: eventName + in: path description: >- - Devices may connect to the Care Daily AI Platform with a persistent HTTP connection or a web socket. -
- true - The server will check for an active persistent connection with the device, and overwrite the previously declared 'connected' value. -
- false - Do not check for persistent connections when declaring the device "connected" (faster, more efficient) -
- Not Set - the server will check for a persistent connection only for devices which were not previously declared 'connected'. + Developer-defined name of the scene. For example, 'HOME', 'AWAY', 'SLEEP', 'VACATION', 'FOOSBALL'. + You can define any name you want. + The name represents some state, and can be fed into Rules and other areas of the app. + required: true schema: - type: boolean - - name: getTags + type: string + requestBody: + content: + application/json: + example: + comment: Optional, why this event sent + schema: + type: object + properties: + comment: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + + /cloud/json/location/{locationId}/events: + get: + summary: Location Scenes History + operationId: Location Scenes History + description: |- + Return location change schemes history in backward order (latest first). + + Source types: + + | Type | Description | + | :--: | ----------- | + | 0 | User app | + | 1 | Rule | + | 2 | Bot | + | 9 | Third-party OAuth client | + tags: + - Location Events + security: + - userApiKey: [] + parameters: + - name: locationId + in: path + description: The Location ID + required: true + schema: + type: integer + - name: startDate in: query - description: Return device tags + description: Start date to begin receiving data schema: - type: boolean - - name: prospect + type: string + - name: endDate in: query - description: Return prospect devices + description: End date to stop receiving data. Default is the current date. schema: - type: boolean + type: string responses: '200': - description: Device instances + description: Location Scenes content: application/json: schema: @@ -5608,582 +5096,304 @@ paths: properties: resultCode: type: integer - devices: + events: type: array items: type: object properties: - id: - type: string - description: Device ID - type: - type: integer - description: Device Type - typeCategory: - type: integer - description: Device Type Category - goalId: - type: integer - description: Device usage goal ID - locationId: - type: integer - description: Device location ID - desc: - type: string - description: Device name or description - connected: - type: boolean - description: Device connection status - modelId: - type: string - description: Device model ID - lastDataReceivedDate: - type: string - description: Last time, when any data received for this device - lastDataReceivedDateMs: - type: integer - lastMeasureDate: + event: type: string - description: Last time, when device measurements received - lastMeasureDateMs: - type: integer - lastConnectedDate: + description: Scene value + eventDate: type: string - description: Last time, when disconnected device appeared to be online - lastConnectedDateMs: + description: Scene date + eventDateMs: type: integer - proxyId: - type: string - description: Device proxy or hub ID - zoneId: - type: string - description: Device zone ID - applicationId: + sourceType: type: integer - description: Device integration cloud ID - authId: - type: string - description: Device integration authentication ID - newDevice: - type: boolean - description: If the device is marked as just registered - icon: + description: Client's type which set the scene + sourceAgent: type: string - description: Device type icon - simulated: - type: integer - description: Simulated device status - simulatedPrefix: + description: HTTP User-Agent header value + comment: type: string - typeAttributes: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - required: - - name - - value - parameters: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - lastUpdateTime: - type: string - lastUpdateTimeMs: - type: integer - index: - type: string - required: - - name - - value - - lastUpdateTime - - lastUpdateTimeMs - spaces: - type: array - items: - type: object - properties: - id: - type: integer - type: - type: integer - name: - type: string required: - - id - - type - - typeCategory - - locationId - - connected + - event + - eventDate + - eventDateMs example: resultCode: 0 - devices: - - id: 470FF274-8700-44AB-A273-A70691A3C140::4 - type: 24 - typeCategory: 6 - goalId: 123 - locationId: 5 - desc: iPhone 6 - connected: true - newDevice: false - icon: camera - simulated: -1 - simulatedPrefix: SIM1_,SIM2_ - typeAttributes: - - name: deviceListParameterUnits - value: int,int - - name: deviceListParameters - value: motionStatus,accessCameraSettings - parameters: - - name: accessCameraSettings - value: '1' - lastUpdateTime: '2014-12-26T02:31:09-05:00' - lastUpdateTimeMs: 1419579069000 - - name: motionStatus - value: '1' - lastUpdateTime: '2015-01-28T16:46:26-05:00' - lastUpdateTimeMs: 1422481586000 - spaces: - - id: 123 - type: 1 - name: Living room - - id: ea5101a8005f-10031-470 - type: 10031 - typeCategory: 18000 - goalId: 124 - locationId: 5 - desc: Gateway - modelId: CareDailyGateway - lastDataReceivedDate: '2014-06-20T12:47:11-07:00' - lastDataReceivedDateMs: 1403293631000 - lastMeasureDate: '2014-06-20T12:47:11-07:00' - lastMeasureDateMs: 1403293631000 - lastConnectedDate: '2014-06-20T12:47:11-07:00' - lastConnectedDateMs: 1403293631000 - connected: false - newDevice: false - icon: gateway - - id: virtualpsm-6-4e7 - type: 6 - typeCategory: 11000 - locationId: 5 - desc: Light - lastDataReceivedDate: '2014-05-08T02:22:02-07:00' - lastDataReceivedDateMs: 1399540922000 - lastMeasureDate: '2014-05-08T02:22:02-07:00' - lastMeasureDateMs: 1399540922000 - lastConnectedDate: '2014-04-20T12:47:11-07:00' - lastConnectedDateMs: 1383293631000 - connected: false - proxyId: virtualhub-4-4D4 - newDevice: true - typeAttributes: - - name: deviceListParameterUnits - value: W,string - - name: deviceListParameters - value: power,outletStatus - parameters: - - name: outletStatus - value: '1' - lastUpdateTime: '2015-01-12T07:41:54-05:00' - lastUpdateTimeMs: 1421066514000 - - name: power - index: A - value: '10' - lastUpdateTime: '2013-11-20T21:13:09-05:00' - lastUpdateTimeMs: 1384999989000 + events: + - event: HOME + eventDate: '2015-10-01T18:00:00Z' + eventDateMs: 1443722400000 + sourceType: 0 + sourceAgent: Care/4.0.19 (iPhone; iOS 10.3.3; Scale/2.00) + - event: AWAY + eventDate: '2015-09-15T18:00:00Z' + eventDateMs: 1442340000000 + sourceType: 1 + comment: Did not detect motions for one hour + - event: HOME + eventDate: '2015-09-01T18:00:00Z' + eventDateMs: 1441130400000 + sourceType: 2 + comment: Recognized a tenant - delete: - summary: Delete Devices - operationId: Delete Devices + + /cloud/json/locations/{locationId}/narratives: + put: + summary: Create or Update a Narrative + operationId: Create or Update a Narrative description: |- - There are multiple ways to delete a device. - This method is the most flexible, allowing multiple devices to be deleted simultaneously. + Narratives are time-series auditable records that log human-readable events from a location. + They are typically used to enable Explainable AI, and record exactly what happened at what time in a home or business. + Narratives can include arbitrary JSON content underneath the human-visible layer to enable debugging and analytics. + + Friends and family who can switch into and view your location should be able to see your narrative. + + Administrators should also be able to access your narrative in Maestro for debugging / understanding / explanation of "why did that happen in my home?" purposes. - Devices linked to a proxy will be removed from the proxy. + | Status | Description | + | :----: | ----------- | + | 0 | Default initial | + | 1 | Deleted | + | ... | Any other value | + + | Type | Description | + | :--: | ----------- | + | 0 | High-frequency time-series "observations", default | + | 1 | Deleted user (organization) | + | 2 | Deleted location (organization) | + | 3 | Moved location (organization) | + | 4 | Low-frequency time-series "journal" | + | 5 | Insight | + | 6 | Support Ticket | + + Narrative time is always truncated to seconds by the API. + + When a new narrative is created, the API returns the new record ID and `narrativeTime` in milliseconds. + + To update an existing narrative record both `narrativeId` and `narrativeTime` query parameters must be provided. + The new value of `narrativeTime` in milliseconds will be returned, if it has been changed. tags: - - Devices + - Location Events security: - userApiKey: [] + - botApiKey: [] parameters: - - name: deviceId - in: query - description: >- - The Device ID to delete. - You may include this parameter multiple times to delete multiple devices. - required: true - schema: - type: string - name: locationId - in: query - description: Location ID where to delete devices + in: path + description: Location ID required: true schema: type: integer - - name: keepOnAccount + - name: scope in: query - description: Send only a delete command to the gateway, but keep the device on the user's account. + description: Scope:
1 = location,
2 = organization + required: true schema: - type: boolean - - name: keepSlave + type: integer + enum: [1,2] + - name: publish in: query - description: On deleting only a gateway from the user's account, keep dependant slave devices. + description: Publish narrative to subscribers, default is true schema: type: boolean - - name: keepSlaveOnGateway + - name: store in: query - description: On deleting a gateway, do not send delete commands for all dependant slave devices. + description: |- + Store a new narrative in the database, default is true.
+ Can be set to `false`, if it is only for publishing. schema: type: boolean - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/json/devices/{deviceId}: - get: - summary: Get Device by ID - operationId: Get Device by ID - description: |- - Test if the device is owned by this user. - If YES, the API will provide the device and the linked location information. - Otherwise, it will return an error code and only device type and category. - - * The `lastDataReceivedDate` is the last timestamp at which the Care Daily AI Platform received and stored data from this device. - * The `lastMeasureDate` is the last timestamp of measured data from this device. - * The `startDate` is when this device was registered. - tags: - - Devices - security: - - userApiKey: [] - parameters: - - name: deviceId - in: path - description: Device ID to obtain information on - required: true - schema: - type: string - - name: checkConnected + - name: narrativeId in: query - description: Check the device connection status + description: ID of narrative for update schema: - type: boolean - - name: locationId + type: integer + - name: narrativeTime in: query - description: Location ID - required: true + description: narrative time as returned from the API for update schema: type: integer - responses: - '200': - description: Device information - content: - application/json: + requestBody: + content: + application/json: + example: + narrative: + narrativeTime: 1537692964000 + priority: 1 + status: 0 + narrativeType: 0 + eventType: thermostat + icon: icon.gif + iconFont: icon.font + title: Water Leak + description: Water leak in the bathroom + target: + fileIDs: + - 1234 + - 2366 + field: value + schema: + type: object + properties: + narrative: + type: object + properties: + narrativeTime: + type: integer + description: Narrative time in milliseconds for a new record + escalationId: + type: integer + description: Escalation ID + parentId: + type: integer + description: Parent narrative ID + parentNarrativeTime: + type: integer + description: Parent narrative time in milliseconds + priority: + type: integer + status: + type: integer + narrativeType: + type: integer + eventType: + type: string + icon: + type: string + iconFont: + type: string + title: + type: string + description: + type: string + target: + type: object + description: Flexible sructure object + responses: + '200': + description: New narrative ID + content: + application/json: schema: type: object properties: resultCode: type: integer - location: - type: object - properties: - id: - type: integer - name: - type: string - startDate: - type: string - startDateMs: - type: integer - event: - type: string - device: - type: object - properties: - id: - type: string - description: Device ID - type: - type: integer - description: Device Type - typeCategory: - type: integer - description: Device Type Category - goalId: - type: integer - description: Device usage goal ID - locationId: - type: integer - description: Device location ID - desc: - type: string - description: Device name or description - connected: - type: boolean - description: Device connection status - modelId: - type: string - description: Device model ID - lastDataReceivedDate: - type: string - description: Last time, when any data received for this device - lastDataReceivedDateMs: - type: integer - lastMeasureDate: - type: string - description: Last time, when device measurements received - lastMeasureDateMs: - type: integer - lastConnectedDate: - type: string - description: Last time, when disconnected device appeared to be online - lastConnectedDateMs: - type: integer - proxyId: - type: string - description: Device proxy or hub ID - zoneId: - type: string - description: Device zone ID - applicationId: - type: integer - description: Device integration cloud ID - authId: - type: string - description: Device integration authentication ID - newDevice: - type: boolean - description: If the device is marked as just registered - icon: - type: string - description: Device type icon - simulated: - type: integer - description: Simulated device status - simulatedPrefix: - type: string - typeAttributes: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - required: - - name - - value - parameters: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - lastUpdateTime: - type: string - lastUpdateTimeMs: - type: integer - required: - - name - - value - - lastUpdateTime - - lastUpdateTimeMs - tags: - type: array - items: - type: object - properties: - tag: - type: string - organizationId: - type: integer - appId: - type: integer - required: - - tag - spaces: - type: array - items: - type: object - properties: - id: - type: integer - type: - type: integer - name: - type: string - simCards: - type: array - items: - type: object - properties: - id: - type: string - status: - type: integer - serialNumber: - type: string - carrierName: - type: string - lifecycleStatus: - type: string - activationDateMs: - type: integer - inactivationDateMs: - type: integer + narrativeId: + type: integer + narrativeTime: + type: integer example: resultCode: 0 - location: - id: 70 - name: My location - startDate: '2013-03-22T17:27:28-04:00' - startDateMs: 1363987648000 - event: HOME - device: - id: 021DE57B-55F0-4FC0-B0AC-9FCB9AF8A001::71 - type: 24 - goalId: 123 - typeCategory: 6 - locationId: 70 - desc: My camera - lastDataReceivedDate: '2015-04-25T02:29:20-04:00' - lastDataReceivedDateMs: 1429943360000 - lastMeasureDate: '2015-04-25T02:29:20-04:00' - lastMeasureDateMs: 1429943360000 - lastConnectedDate: '2015-04-25T02:29:20-04:00' - lastConnectedDateMs: 1429943360000 - connected: true - newDevice: false - simulated: -1 - simulatedPrefix: SIM1_,SIM2_ - typeAttributes: - - name: deviceListIcon - value: camera - - name: deviceListParameterUnits - value: int,int,int,int - - name: deviceListParameters - value: >- - motionStatus,accessCameraSettings,ppc.robotConnected,ppc.alarm - parameters: - - name: accessCameraSettings - value: '1' - lastUpdateTime: '2015-02-08T15:41:46-05:00' - lastUpdateTimeMs: 1423428106000 - - name: motionStatus - value: '0' - lastUpdateTime: '2015-02-08T15:41:46-05:00' - lastUpdateTimeMs: 1423428106000 - - name: ppc.robotConnected - value: '0' - lastUpdateTime: '2015-02-08T15:41:46-05:00' - lastUpdateTimeMs: 1423428106000 - tags: - - tag: hvac - organizationId: 123 - - tag: efficient - appId: 45 - spaces: - - id: 123 - type: 1 - name: Living room - simCards: - - id: '8901260021105854428' - status: 4 - serialNumber: cmp-k1-subscription-47076309 - carrierName: KATTCC - lifecycleStatus: Suspended - activationDateMs: 1423428106000 - inactivationDateMs: 1423429306000 - + narrativeId: 123 + narrativeTime: 1537692964000 - /cloud/json/locations/{locationId}/devices/{deviceId}: - put: - summary: Update Device - operationId: Update Device + get: + summary: Get Narratives + operationId: Get Narratives description: |- - Update the device nickname / description, the device goal, the `newDevice` flag, the device model ID, the user ID, or move the device to another location. + The search results are organized by "pages". + Each page contains a set of elements sorted by the `narrativeTime` in descending order. + The pages follow one another in reverse chronological order. - The `startDate` field declares when the device was moved. - By default, this is set to the current time when the API call is made. - With this field, it's possible to retroactively declare that the device was at a different location in the past. + The rowCount parameter specifies the maximum number of elements per page. + The result may include the `nextMarker` property - this means that there are more pages for the current search criteria. + To get the next page, the value of `nextMarker` must be passed to the `pageMarker` parameter on the next API call. tags: - - Devices + - Location Events security: - userApiKey: [] + - botApiKey: [] parameters: - name: locationId in: path - description: Location ID that contains the device + description: Location ID required: true schema: type: integer - - name: deviceId - in: path - description: Device ID to update - required: true + - name: rowCount + in: query + description: Maximum number of elements per page + schema: + type: integer + - name: narrativeId + in: query + description: Filter by ID + schema: + type: integer + - name: narrativeTime + in: query + description: Specific narrative time + schema: + type: integer + - name: escalationId + in: query + description: Escalation ID + schema: + type: integer + - name: parentId + in: query + description: Filter by parent ID + schema: + type: integer + - name: narrativeType + in: query + description: Filter by narrative type, multiple values + schema: + type: integer + - name: scope + in: query + description: Scope:
1 = location, default,
2 = organization, for bots only + schema: + type: integer + enum: [1,2] + - name: priority + in: query + description: Filter by priority higher or equal than that + schema: + type: integer + - name: toPriority + in: query + description: Filter by priority less or equal than that + schema: + type: integer + - name: status + in: query + description: Filter by status, deleted are not returned by default + schema: + type: integer + - name: eventType + in: query + description: Filter by event type + schema: + type: string + - name: searchBy + in: query + description: Filter by title or description. Use * for a wildcard. + schema: + type: string + - name: startDate + in: query + description: Narrative date range start + schema: + type: string + - name: endDate + in: query + description: Narrative date range end + schema: + type: string + - name: pageMarker + in: query + description: Marker to the next page schema: type: string - requestBody: - content: - application/json: - example: - device: - desc: description - goalId: 123 - modelId: DeviceModelId - newDevice: false - userId: 123 - location: - id: 23 - startDate: '2013-07-17T10:59:15-04:00' - schema: - type: object - properties: - device: - type: object - properties: - desc: - type: string - goalId: - type: integer - modelId: - type: string - newDevice: - type: boolean - userId: - type: integer - location: - type: object - properties: - id: - type: integer - startDate: - type: string responses: '200': - description: OK + description: Narratives content: application/json: schema: @@ -6191,80 +5401,139 @@ paths: properties: resultCode: type: integer + nextMarker: + type: string + description: Pass it to the `pageMarker` parameter on the next API call + narratives: + type: array + items: + type: object + properties: + id: + type: integer + locationId: + type: integer + narrativeDate: + type: string + narrativeDateMs: + type: integer + creationDate: + type: string + creationDateMs: + type: integer + narrativeType: + type: integer + priority: + type: integer + status: + type: integer + icon: + type: string + title: + type: string + description: + type: string + target: + type: object + description: Flexible structure object + appInstanceId: + type: integer + description: Bot instance ID, which created this record + iconFont: + type: string + required: + - id + - locationId + - narrativeDate + - narrativeDateMs + - creationDate + - creationDateMs + - narrativeType + - priority + - status example: resultCode: 0 + nextMarker: 16611d93630-306b + narratives: + - id: 20 + locationId: 1 + narrativeDate: '2018-10-01T03:05:07' + narrativeDateMs: 1537692964000 + creationDate: '2018-10-01T03:05:07' + creationDateMs: 1537692964000 + narrativeType: 0 + priority: 3 + status: 0 + icon: alert.gif + title: Water Leak + description: Water leak in the bathroom + target: + field: value + appInstanceId: 520 + - id: 19 + locationId: 1 + narrativeDate: '2018-10-01T03:05:07' + narrativeDateMs: 1537692964000 + creationDate: '2018-10-01T03:05:07' + creationDateMs: 1537692964000 + narrativeType: 0 + priority: 1 + status: 2 + icon: icon4 + iconFont: icon.font + title: Left the house + description: Left the house + target: + field: value + appInstanceId: 520 delete: - summary: Delete Device - operationId: Delete Device - description: |- - There are multiple ways to delete a device. - This ability to delete a device from a specific location is useful for system and organization administrators. - - Devices linked to a proxy will be removed from the proxy. + summary: Delete a Narrative + operationId: Delete a Narrative + description: '' tags: - - Devices + - Location Events security: - - userApiKey: [] + - botApiKey: [] parameters: - name: locationId in: path - description: Location ID to delete a device from + description: Location ID required: true schema: type: integer - - name: deviceId - in: path - description: The Device ID to delete + - name: scope + in: query + description: Scope:
1 = location,
2 = organization required: true schema: - type: string - - name: keepOnAccount + type: integer + enum: [1,2] + - name: narrativeId in: query - description: Send only a delete command to the gateway, but keep the device on the user's account. + description: ID of narrative to delete + required: true schema: - type: boolean - - name: keepSlave + type: integer + - name: narrativeTime in: query - description: On deleting only a gateway from the user's account, keep dependant slave devices. + description: narrative time in milliseconds + required: true schema: - type: boolean - - name: keepSlaveOnGateway + type: integer + - name: publish in: query - description: On deleting a gateway, do not send delete commands for all dependant slave devices. + description: Publish narrative to subscribers, default is true schema: type: boolean - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/json/preregistered/{deviceId}: - get: - summary: Get pre-registered device by ID - operationId: Get pre-registered device - description: This API returns device type and model, if this information is pre-registered in the cloud database. - tags: - - Devices - parameters: - - name: deviceId - in: path - description: Device ID - required: true + - name: eventType + in: query + description: Publishing event type schema: type: string responses: '200': - description: Device details + description: OK content: application/json: schema: @@ -6272,86 +5541,81 @@ paths: properties: resultCode: type: integer - device: - type: object - properties: - id: - type: string - description: Device ID - type: - type: string - description: Device type - typeCategory: - type: string - description: Device type category - modelId: - type: integer - description: Device model ID - required: - - id - - type example: resultCode: 0 - device: - id: ABC123 - type: 37 - typeCategory: 18000 - modelId: gateway - /cloud/json/locations/{locationId}/devices/{deviceId}/simCard: - put: - summary: Activate Sim Card - operationId: Activate Sim Card - tags: - - Devices + /clouse/json/openai: + post: + summary: Send a request to OpenAI + operationId: Send a request to OpenAI description: |- - Using this API an administrator can manually activate or deactivate device SIM cards. - - SIM cards linked to the device are returned by the get device by ID API. - - A status of a SIM card can have following values: + Send a synchronous request to OpenAI API to obtain a model response for the given chat conversation. + + The response from CharGPT is returned by the API and can look like: - | Status | Name | Details | - | :----: | ---- | ------- | - | 0 | New | Can be Activated | - | 1 | Active | Can be Deactivated | - | 2 | Reserved | | - | 3 | Expired | | - | 4 | Suspended | Can be Deactivated | - | 5 | Deactivated | Can be Activated | - | 6 | Cancelled | | - | 7 | Not Exist | | + > + { + "id" : "chatcmpl-86GKbsl3bP5YmmxutIY8aS5c5o5gK", + "object" : "chat.completion", + "created" : 1696503437, + "model" : "gpt-3.5-turbo-0613", + "choices" : [ + { + "index" : 0, + "message" : { + "role" : "assistant", + "content" : "This is a test!" + }, + "finish_reason" : "stop" + } + ], + "usage" : { + "prompt_tokens" : 13, + "completion_tokens" : 5, + "total_tokens" : 18 + } + } + tags: + - Location Events security: - - adminApiKey: [] + - userApiKey: [] parameters: - name: locationId - in: path + in: query description: Location ID required: true schema: type: integer - - name: deviceId - in: path - description: Device ID - required: true + - name: openAiOrganization + in: query + description: An organization which will be used (charged) for an Open AI API request. schema: type: string - - name: status + - name: openAiPath in: query - description: New SIM card status:
1 = active
5 = deactivated + description: |- + A path index which will be used for an Open AI API request.
+ Available values are
+ 0 - /v1/chat/completions,
+ 1 - /v1/responses. required: true schema: type: integer - enum: [1,5] - - name: simId - in: query - description: SIM ID - schema: - type: integer + requestBody: + content: + application/json: + example: + answer: + model: gpt-5 + input: Some text for the Responses API + messages: + - content: Some text for the Chat Completions API + role: user + temperature: 0.7 responses: '200': - description: OK + description: OpenAI response content: application/json: schema: @@ -6359,40 +5623,38 @@ paths: properties: resultCode: type: integer + answer: + type: object example: resultCode: 0 - /cloud/json/locations/{locationId}/devices/{deviceId}/copySimulator: - post: - summary: Create Device Simulated Copy - operationId: Create Device Simulated Copy - description: Using this API an administrator can set a device as a source simulator and register another simulated device on a required location. + /clouse/json/openaiToken: + get: + summary: Get OpenAI client token + operationId: Get OpenAI client token + description: |- + Send a synchronous request to OpenAI API to retrieve an ephemeral token. tags: - - Devices + - Location Events security: - - adminApiKey: [] + - userApiKey: [] parameters: - name: locationId - in: path - description: Location ID that contains the source device + in: query + description: Location ID required: true schema: type: integer - - name: deviceId - in: path - description: Device ID acting as a source - required: true - schema: - type: string - - name: simulatedLocationId + - name: expiry in: query - description: Location ID where a simulated devise will be registered + description: An optional expiry in seconds + required: true schema: type: integer responses: '200': - description: Simulated device ID + description: OpenAI response content: application/json: schema: @@ -6400,187 +5662,116 @@ paths: properties: resultCode: type: integer - deviceId: - type: string - description: Simulated device ID + answer: + type: object example: resultCode: 0 - deviceId: SIM1_DEVICE_ID - /cloud/json/devices/{deviceId}/services: - get: - summary: Get Services by Device - operationId: Get Services by Device + /cloud/json/devices: + post: + summary: Register a Device + operationId: Register a Device description: |- - A gateway or proxy can request a list of assigned subscription services to the device and the location. - - The `PPCAuthorization` headers may take on one form to identify the source device: - * Using a Device Authentication Token: `PPCAuthorization: esp token="ABC12345"` + Registration response will describe how the device should connect to the cloud server instance. tags: - Devices + security: + - userApiKey: [] parameters: - name: deviceId - in: path - description: Device ID of the gateway or proxy - required: true + in: query + description: Globally unique device identifier for this device. Must be 50 or less characters long, and must not contain '/', '%', '#', or '+' characters. schema: type: string - - name: PPCAuthorization - in: header - description: Device's authorization - required: true + - name: locationId + in: query + description: The Location to add this device to. Mandatory when called by a user. + schema: + type: integer + - name: proxyId + in: query + description: Send the add device command to this proxy schema: type: string - example: esp token=ABC12345 - responses: - '200': - description: Services - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - services: - type: array - items: - type: object - properties: - name: - type: string - amount: - type: integer - startDate: - type: string - startDateMs: - type: integer - endDate: - type: string - endDateMs: - type: integer - required: - - name - - amount - - startDate - - startDateMs - - endDate - - endDateMs - example: - resultCode: 0 - services: - - name: Care Pro - amount: 1 - startDate: '2014-05-01T12:00:00Z' - startDateMs: 1398945600000 - endDate: '2014-06-01T12:00:00Z' - endDateMs: 1401624000000 - - name: DeviceFileSpace - amount: 2147483648 - startDate: '2014-05-01T12:00:00Z' - startDateMs: 1398945600000 - endDate: '2014-06-01T12:00:00Z' - endDateMs: 1401624000000 - - - /cloud/json/locations/{locationId}/deviceActivation/{deviceType}: - get: - summary: Get Device Activation Info - operationId: Get Device Activation Info - description: >- - Some devices require manual interaction to complete registration in the Care Daily AI Platform. - This API returns a device activation key. - tags: - - Devices - security: - - userApiKey: [] - parameters: - - name: locationId - in: path - description: Location ID to register a device - required: true - schema: - type: integer - name: deviceType - in: path - description: Device type ID - required: true + in: query + description: Type of the device being registered. Optional, but highly recommended you specify this. schema: type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - deviceActivationKey: - type: string - example: - resultCode: 0 - deviceActivationKey: "3:20Q9mYSH14s0M4v5o" - - - /cloud/json/devices/{deviceId}/properties: - post: - summary: Set Device Properties - operationId: Set Device Properties - description: A Device Property allows you to associate some extra key/value information with a particular device. Device Property keys and values can be 250 characters maximum. - tags: - - Devices - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: deviceId - in: path - description: Device ID to set a key/value property for - required: true + - name: authToken + in: query + description: |- + The Care Daily AI Platform takes security a leap forward by allowing the use of an optional cryptographic authentication token to be used for bi-directional authentication of a device. + If requested, your device will be responsible for securely storing the generated authentication token and including it in all future HTTP requests to the Care Daily AI Platform. +
true - Request an authentication token +
false - No authentication token necessary + schema: + type: boolean + - name: startDate + in: query + description: |- + Timestamp at which to register this device in milliseconds or ISO 8601. +
The Care Daily AI Platform will ignore inbound measurements with a timestamp before the registration time. +
Default is the current time. schema: type: string - - name: locationId + - name: desc in: query - description: Device location ID - required: true + description: Device nickname / description + schema: + type: string + - name: goalId + in: query + description: Device usage goal ID + schema: + type: integer + - name: modelId + in: query + description: Device model ID + schema: + type: integer + - name: userId + in: query + description: User ID associated with a personal device schema: type: integer + - name: ACTIVATION_KEY + in: header + description: Device activation key, if the API key is not provided + schema: + type: string requestBody: content: application/json: example: - property: - - name: size - value: '10' - - name: xMin - index: '1' - value: '1.5' + properties: + - name: username + value: admin + - name: port + index: '01' + value: '1234' schema: type: object properties: - property: + properties: type: array + description: Name/value properties items: type: object properties: name: type: string - description: Property name value: type: string - description: Property value index: type: string - description: Optional property index required: - name - value responses: '200': - description: OK + description: Device regisration result content: application/json: schema: @@ -6588,43 +5779,97 @@ paths: properties: resultCode: type: integer + deviceId: + type: string + authToken: + type: string + deviceType: + type: integer + locationId: + type: integer + exist: + type: boolean + description: true if the device exists on the location already + config: + type: object + description: Flexible structure object depending on the device type for device provisioning and initial configuration + host: + type: string + description: Connection settings for Care Daily device IO connected devices + port: + type: integer + useSSL: + type: boolean example: resultCode: 0 + deviceId: globally-unique-device-id + authToken: generated device authentication token + deviceType: 123 + locationId: 456 + exist: false + host: esp.peoplepowerco.com + port: 8443 + useSSL: true get: - summary: Get Device Properties - operationId: Get Device Properties + summary: Get Devices + operationId: Get Devices + description: |- + Returns a list of devices belonging to the location. + Also this API returns some UI specific device type attributes and device parameters. + + | Simulated | Description | + | :-------: | ----------- | + | -1 | Real device which data copied to simulated devices | + | 1 | Device data simulated by the cloud scheduler | + | 2 | Device data copied from a real device | + | 3 | Device data simulated by a "flexible" simulator | tags: - Devices security: - userApiKey: [] - - botApiKey: [] parameters: - - name: deviceId - in: path - description: Device ID for which to retrieve device properties - required: true - schema: - type: string - name: locationId in: query - description: Device location ID + description: Location ID required: true schema: type: integer - - name: name + - name: spaceId in: query - description: Optional name of the property to retrieve + description: Filter devices by space ID schema: - type: string - - name: index + type: integer + - name: spaceType in: query - description: Optional index value of the property to retrieve + description: Filter devices by space type schema: - type: string + type: integer + - name: checkPersistent + in: query + description: >- + Devices may connect to the Care Daily AI Platform with a persistent HTTP connection or a web socket. +
+ true - The server will check for an active persistent connection with the device, and overwrite the previously declared 'connected' value. +
+ false - Do not check for persistent connections when declaring the device "connected" (faster, more efficient) +
+ Not Set - the server will check for a persistent connection only for devices which were not previously declared 'connected'. + schema: + type: boolean + - name: getTags + in: query + description: Return device tags + schema: + type: boolean + - name: prospect + in: query + description: Return prospect devices + schema: + type: boolean responses: '200': - description: Properties + description: Device instances content: application/json: schema: @@ -6632,66 +5877,242 @@ paths: properties: resultCode: type: integer - properties: + devices: type: array items: type: object properties: - name: - type: string - value: + id: type: string - index: + description: Device ID + type: + type: integer + description: Device Type + typeCategory: + type: integer + description: Device Type Category + goalId: + type: integer + description: Device usage goal ID + locationId: + type: integer + description: Device location ID + desc: type: string - required: - - name - - value + description: Device name or description + connected: + type: boolean + description: Device connection status + modelId: + type: string + description: Device model ID + lastDataReceivedDate: + type: string + description: Last time, when any data received for this device + lastDataReceivedDateMs: + type: integer + lastMeasureDate: + type: string + description: Last time, when device measurements received + lastMeasureDateMs: + type: integer + lastConnectedDate: + type: string + description: Last time, when disconnected device appeared to be online + lastConnectedDateMs: + type: integer + proxyId: + type: string + description: Device proxy or hub ID + zoneId: + type: string + description: Device zone ID + applicationId: + type: integer + description: Device integration cloud ID + authId: + type: string + description: Device integration authentication ID + newDevice: + type: boolean + description: If the device is marked as just registered + icon: + type: string + description: Device type icon + simulated: + type: integer + description: Simulated device status + simulatedPrefix: + type: string + typeAttributes: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + required: + - name + - value + parameters: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + lastUpdateTime: + type: string + lastUpdateTimeMs: + type: integer + index: + type: string + required: + - name + - value + - lastUpdateTime + - lastUpdateTimeMs + spaces: + type: array + items: + type: object + properties: + id: + type: integer + type: + type: integer + name: + type: string + required: + - id + - type + - typeCategory + - locationId + - connected example: resultCode: 0 - properties: - - name: color - value: white - - name: texture - value: smooth - - name: appliance - index: '0' - value: TV - - name: appliance - index: '1' - value: DVR + devices: + - id: 470FF274-8700-44AB-A273-A70691A3C140::4 + type: 24 + typeCategory: 6 + goalId: 123 + locationId: 5 + desc: iPhone 6 + connected: true + newDevice: false + icon: camera + simulated: -1 + simulatedPrefix: SIM1_,SIM2_ + typeAttributes: + - name: deviceListParameterUnits + value: int,int + - name: deviceListParameters + value: motionStatus,accessCameraSettings + parameters: + - name: accessCameraSettings + value: '1' + lastUpdateTime: '2014-12-26T02:31:09-05:00' + lastUpdateTimeMs: 1419579069000 + - name: motionStatus + value: '1' + lastUpdateTime: '2015-01-28T16:46:26-05:00' + lastUpdateTimeMs: 1422481586000 + spaces: + - id: 123 + type: 1 + name: Living room + - id: ea5101a8005f-10031-470 + type: 10031 + typeCategory: 18000 + goalId: 124 + locationId: 5 + desc: Gateway + modelId: CareDailyGateway + lastDataReceivedDate: '2014-06-20T12:47:11-07:00' + lastDataReceivedDateMs: 1403293631000 + lastMeasureDate: '2014-06-20T12:47:11-07:00' + lastMeasureDateMs: 1403293631000 + lastConnectedDate: '2014-06-20T12:47:11-07:00' + lastConnectedDateMs: 1403293631000 + connected: false + newDevice: false + icon: gateway + - id: virtualpsm-6-4e7 + type: 6 + typeCategory: 11000 + locationId: 5 + desc: Light + lastDataReceivedDate: '2014-05-08T02:22:02-07:00' + lastDataReceivedDateMs: 1399540922000 + lastMeasureDate: '2014-05-08T02:22:02-07:00' + lastMeasureDateMs: 1399540922000 + lastConnectedDate: '2014-04-20T12:47:11-07:00' + lastConnectedDateMs: 1383293631000 + connected: false + proxyId: virtualhub-4-4D4 + newDevice: true + typeAttributes: + - name: deviceListParameterUnits + value: W,string + - name: deviceListParameters + value: power,outletStatus + parameters: + - name: outletStatus + value: '1' + lastUpdateTime: '2015-01-12T07:41:54-05:00' + lastUpdateTimeMs: 1421066514000 + - name: power + index: A + value: '10' + lastUpdateTime: '2013-11-20T21:13:09-05:00' + lastUpdateTimeMs: 1384999989000 delete: - summary: Delete a Device Property - operationId: Delete a Device Property + summary: Delete Devices + operationId: Delete Devices + description: |- + There are multiple ways to delete a device. + This method is the most flexible, allowing multiple devices to be deleted simultaneously. + + Devices linked to a proxy will be removed from the proxy. tags: - Devices security: - userApiKey: [] - - botApiKey: [] parameters: - name: deviceId - in: path - description: Device ID + in: query + description: >- + The Device ID to delete. + You may include this parameter multiple times to delete multiple devices. required: true schema: type: string - name: locationId in: query - description: Device location ID + description: Location ID where to delete devices required: true schema: type: integer - - name: name + - name: keepOnAccount in: query - description: Name of the property to delete - required: true + description: Send only a delete command to the gateway, but keep the device on the user's account. schema: - type: string - - name: index + type: boolean + - name: keepSlave in: query - description: Optional index value of the property to delete + description: On deleting only a gateway from the user's account, keep dependant slave devices. schema: - type: string + type: boolean + - name: keepSlaveOnGateway + in: query + description: On deleting a gateway, do not send delete commands for all dependant slave devices. + schema: + type: boolean responses: '200': description: OK @@ -6706,37 +6127,43 @@ paths: resultCode: 0 - /cloud/json/locations/{locationId}/devices/{deviceId}/spaces/{spaceId}: - put: - summary: Link Device Space - operationId: Link Space - description: A user can map devices to location spaces. Each device can be linked to one or multiple spaces on the same location based on the device type. + /cloud/json/devices/{deviceId}: + get: + summary: Get Device by ID + operationId: Get Device by ID + description: |- + Test if the device is owned by this user. + If YES, the API will provide the device and the linked location information. + Otherwise, it will return an error code and only device type and category. + + * The `lastDataReceivedDate` is the last timestamp at which the Care Daily AI Platform received and stored data from this device. + * The `lastMeasureDate` is the last timestamp of measured data from this device. + * The `startDate` is when this device was registered. tags: - Devices security: - userApiKey: [] parameters: - - name: locationId - in: path - description: Location ID - required: true - schema: - type: integer - name: deviceId in: path - description: Device ID + description: Device ID to obtain information on required: true schema: type: string - - name: spaceId - in: path - description: Space ID + - name: checkConnected + in: query + description: Check the device connection status + schema: + type: boolean + - name: locationId + in: query + description: Location ID required: true schema: type: integer responses: '200': - description: OK + description: Device information content: application/json: schema: @@ -6744,12 +6171,232 @@ paths: properties: resultCode: type: integer - example: - resultCode: 0 + location: + type: object + properties: + id: + type: integer + name: + type: string + startDate: + type: string + startDateMs: + type: integer + event: + type: string + device: + type: object + properties: + id: + type: string + description: Device ID + type: + type: integer + description: Device Type + typeCategory: + type: integer + description: Device Type Category + goalId: + type: integer + description: Device usage goal ID + locationId: + type: integer + description: Device location ID + desc: + type: string + description: Device name or description + connected: + type: boolean + description: Device connection status + modelId: + type: string + description: Device model ID + lastDataReceivedDate: + type: string + description: Last time, when any data received for this device + lastDataReceivedDateMs: + type: integer + lastMeasureDate: + type: string + description: Last time, when device measurements received + lastMeasureDateMs: + type: integer + lastConnectedDate: + type: string + description: Last time, when disconnected device appeared to be online + lastConnectedDateMs: + type: integer + proxyId: + type: string + description: Device proxy or hub ID + zoneId: + type: string + description: Device zone ID + applicationId: + type: integer + description: Device integration cloud ID + authId: + type: string + description: Device integration authentication ID + newDevice: + type: boolean + description: If the device is marked as just registered + icon: + type: string + description: Device type icon + simulated: + type: integer + description: Simulated device status + simulatedPrefix: + type: string + typeAttributes: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + required: + - name + - value + parameters: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + lastUpdateTime: + type: string + lastUpdateTimeMs: + type: integer + required: + - name + - value + - lastUpdateTime + - lastUpdateTimeMs + tags: + type: array + items: + type: object + properties: + tag: + type: string + organizationId: + type: integer + appId: + type: integer + required: + - tag + spaces: + type: array + items: + type: object + properties: + id: + type: integer + type: + type: integer + name: + type: string + simCards: + type: array + items: + type: object + properties: + id: + type: string + status: + type: integer + serialNumber: + type: string + carrierName: + type: string + lifecycleStatus: + type: string + activationDateMs: + type: integer + inactivationDateMs: + type: integer + example: + resultCode: 0 + location: + id: 70 + name: My location + startDate: '2013-03-22T17:27:28-04:00' + startDateMs: 1363987648000 + event: HOME + device: + id: 021DE57B-55F0-4FC0-B0AC-9FCB9AF8A001::71 + type: 24 + goalId: 123 + typeCategory: 6 + locationId: 70 + desc: My camera + lastDataReceivedDate: '2015-04-25T02:29:20-04:00' + lastDataReceivedDateMs: 1429943360000 + lastMeasureDate: '2015-04-25T02:29:20-04:00' + lastMeasureDateMs: 1429943360000 + lastConnectedDate: '2015-04-25T02:29:20-04:00' + lastConnectedDateMs: 1429943360000 + connected: true + newDevice: false + simulated: -1 + simulatedPrefix: SIM1_,SIM2_ + typeAttributes: + - name: deviceListIcon + value: camera + - name: deviceListParameterUnits + value: int,int,int,int + - name: deviceListParameters + value: >- + motionStatus,accessCameraSettings,ppc.robotConnected,ppc.alarm + parameters: + - name: accessCameraSettings + value: '1' + lastUpdateTime: '2015-02-08T15:41:46-05:00' + lastUpdateTimeMs: 1423428106000 + - name: motionStatus + value: '0' + lastUpdateTime: '2015-02-08T15:41:46-05:00' + lastUpdateTimeMs: 1423428106000 + - name: ppc.robotConnected + value: '0' + lastUpdateTime: '2015-02-08T15:41:46-05:00' + lastUpdateTimeMs: 1423428106000 + tags: + - tag: hvac + organizationId: 123 + - tag: efficient + appId: 45 + spaces: + - id: 123 + type: 1 + name: Living room + simCards: + - id: '8901260021105854428' + status: 4 + serialNumber: cmp-k1-subscription-47076309 + carrierName: KATTCC + lifecycleStatus: Suspended + activationDateMs: 1423428106000 + inactivationDateMs: 1423429306000 - delete: - summary: Unlink Device Space - operationId: Unlink Space + + /cloud/json/locations/{locationId}/devices/{deviceId}: + put: + summary: Update Device + operationId: Update Device + description: |- + Update the device nickname / description, the device goal, the `newDevice` flag, the device model ID, the user ID, or move the device to another location. + + The `startDate` field declares when the device was moved. + By default, this is set to the current time when the API call is made. + With this field, it's possible to retroactively declare that the device was at a different location in the past. tags: - Devices security: @@ -6757,81 +6404,55 @@ paths: parameters: - name: locationId in: path - description: Location ID + description: Location ID that contains the device required: true schema: type: integer - name: deviceId in: path - description: Device ID + description: Device ID to update required: true schema: type: string - - name: spaceId - in: path - description: Space ID - required: true - schema: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/json/fwupdate: - get: - summary: Get Firmware Jobs - operationId: Get Firmware Jobs - description: |- - A user can approve or decline an update of his devices with new firmware. - - Frimware update job statuses: - - | Status | Description | - | :----: | ----------- | - | 1 | Available | - | 2 | Approved | - | 3 | Decline | - | 4 | Started | - - This API allows to retrieve a list of available firmware updates for user devices. - tags: - - Devices - security: - - userApiKey: [] - parameters: - - name: deviceId - in: query - description: Optional filter by device ID - schema: - type: string - - name: index - in: query - description: Check update for specific device part - schema: - type: string - - name: firmware - in: query - description: Current device firmware version - schema: - type: string - - name: userId - in: query - description: Device owner ID for access by an administrator - schema: - type: integer + requestBody: + content: + application/json: + example: + device: + desc: description + goalId: 123 + modelId: DeviceModelId + newDevice: false + userId: 123 + location: + id: 23 + startDate: '2013-07-17T10:59:15-04:00' + schema: + type: object + properties: + device: + type: object + properties: + desc: + type: string + goalId: + type: integer + modelId: + type: string + newDevice: + type: boolean + userId: + type: integer + location: + type: object + properties: + id: + type: integer + startDate: + type: string responses: '200': - description: Firmware update jobs + description: OK content: application/json: schema: @@ -6839,123 +6460,49 @@ paths: properties: resultCode: type: integer - jobs: - type: array - items: - type: object - properties: - id: - type: integer - description: Job ID - index: - type: string - description: Optional device part to update - firmware: - type: string - description: New firmware version - currentFirmware: - type: string - description: Current firmware version - status: - type: integer - description: Update status - forced: - type: boolean - description: No user's approval required - url: - type: string - description: Firmware downloca URL - checkSum: - type: string - description: Firmware checksum - notificationDate: - type: string - description: Last user's notification date about the available update - notificationDateMs: - type: integer - startDate: - type: string - description: Update start date - startDateMs: - type: integer - device: - type: object - description: Updated device properties - properties: - id: - type: string - type: - type: integer - typeCategory: - type: integer - desc: - type: string - lastDataReceivedDate: - type: string - lastDataReceivedDateMs: - type: integer example: resultCode: 0 - jobs: - - id: 123 - index: BLE - firmware: 1.4.5 - currentFirmware: 1.2.3 - status: 2 - forced: false - url: https://fw.peoplepowerco.com/update_1_0_10.apk - checkSum: 391bd1de48e2539ea2a9795365a313046238e2b8c88fd6b8d4fbb113dbf93085 - notificationDate: '2014-06-20T12:47:11-07:00' - notificationDateMs: 1403293631000 - startDate: '2014-06-20T12:47:11-07:00' - startDateMs: 1403293631000 - device: - id: GATEWAY_ID - type: 31 - typeCategory: 18000 - desc: Gateway - lastDataReceivedDate: '2014-12-26T02:31:09-05:00' - lastDataReceivedDateMs: 1419579069000 - put: - summary: Set Firmware Update Status - operationId: Set Firmware Update Status + + delete: + summary: Delete Device + operationId: Delete Device description: |- - Approve or decline a not forced firmware update job. + There are multiple ways to delete a device. + This ability to delete a device from a specific location is useful for system and organization administrators. - The user can schedule the update after specific date and time. + Devices linked to a proxy will be removed from the proxy. tags: - Devices security: - userApiKey: [] parameters: - - name: deviceId - in: query - description: Device ID + - name: locationId + in: path + description: Location ID to delete a device from required: true schema: - type: string - - name: status - in: query - description: New job status:
2 - approved
3 - declined + type: integer + - name: deviceId + in: path + description: The Device ID to delete required: true schema: - type: integer - enum: [2,3] - - name: index + type: string + - name: keepOnAccount in: query - description: Update firmware of specific device part + description: Send only a delete command to the gateway, but keep the device on the user's account. schema: - type: string - - name: startDate + type: boolean + - name: keepSlave in: query - description: Firmware update start date + description: On deleting only a gateway from the user's account, keep dependant slave devices. schema: - type: string - - name: userId + type: boolean + - name: keepSlaveOnGateway in: query - description: Device owner ID for access by an administrator + description: On deleting a gateway, do not send delete commands for all dependant slave devices. schema: - type: integer + type: boolean responses: '200': description: OK @@ -6970,40 +6517,23 @@ paths: resultCode: 0 - /cloud/json/deviceLogs: + /cloud/json/preregistered/{deviceId}: get: - summary: Get Device Logs - operationId: Get Device Logs - description: Returns a list device log files stored in the system + summary: Get pre-registered device by ID + operationId: Get pre-registered device + description: This API returns device type and model, if this information is pre-registered in the cloud database. tags: - Devices - security: - - userApiKey: [] parameters: - - name: locationId - in: query - description: Request device on a specific location - required: true - schema: - type: integer - name: deviceId - in: query - description: Device ID filter - schema: - type: string - - name: startDate - in: query - description: Limit response by date, 30 days in the past maximum - schema: - type: string - - name: endDate - in: query - description: Limit response by date + in: path + description: Device ID + required: true schema: type: string responses: '200': - description: Device logs + description: Device details content: application/json: schema: @@ -7011,68 +6541,86 @@ paths: properties: resultCode: type: integer - logs: - type: array - items: - type: object - properties: - deviceId: - type: string - logDate: - type: string - logDateMs: - type: integer - size: - type: integer - contentType: - type: string - logType: - type: string - logName: - type: string - example: - resultCode: 0 - logs: - - deviceId: DEVICE_ID - logDate: '2021-09-20T12:47:11-07:00' - logDateMs: 1603293631000 - size: 10000 - contentType: application/octet-stream - logType: logs - logName: '1603293631000' + device: + type: object + properties: + id: + type: string + description: Device ID + type: + type: string + description: Device type + typeCategory: + type: string + description: Device type category + modelId: + type: integer + description: Device model ID + required: + - id + - type + example: + resultCode: 0 + device: + id: ABC123 + type: 37 + typeCategory: 18000 + modelId: gateway - /cloud/json/deviceLogContent: - get: - summary: Get Device Log Content - operationId: Get Device Log Content - description: This API returns a temporary URL to download log's content. + /cloud/json/locations/{locationId}/devices/{deviceId}/simCard: + put: + summary: Activate Sim Card + operationId: Activate Sim Card tags: - Devices + description: |- + Using this API an administrator can manually activate or deactivate device SIM cards. + + SIM cards linked to the device are returned by the get device by ID API. + + A status of a SIM card can have following values: + + | Status | Name | Details | + | :----: | ---- | ------- | + | 0 | New | Can be Activated | + | 1 | Active | Can be Deactivated | + | 2 | Reserved | | + | 3 | Expired | | + | 4 | Suspended | Can be Deactivated | + | 5 | Deactivated | Can be Activated | + | 6 | Cancelled | | + | 7 | Not Exist | | security: - - userApiKey: [] + - adminApiKey: [] parameters: - name: locationId - in: query - description: Request device on a specific location + in: path + description: Location ID required: true schema: type: integer - name: deviceId - in: query + in: path description: Device ID required: true schema: type: string - - name: logDate + - name: status in: query - description: Log date + description: New SIM card status:
1 = active
5 = deactivated required: true schema: - type: string + type: integer + enum: [1,5] + - name: simId + in: query + description: SIM ID + schema: + type: integer responses: '200': - description: Log's content URL + description: OK content: application/json: schema: @@ -7080,61 +6628,40 @@ paths: properties: resultCode: type: integer - url: - type: string example: resultCode: 0 - url: https://s3.amazon.com/logs/abc123?param=value - /cloud/json/devices/{deviceId}/sensitivityMap: + /cloud/json/locations/{locationId}/devices/{deviceId}/copySimulator: post: - summary: Upload Sensitivity Map - operationId: Upload Sensitivity Map - description: >- - The sensitivity map content must be uploaded as octet-stream. - The API will send a command to the device to download the map. + summary: Create Device Simulated Copy + operationId: Create Device Simulated Copy + description: Using this API an administrator can set a device as a source simulator and register another simulated device on a required location. tags: - Devices security: - - userApiKey: [] + - adminApiKey: [] parameters: - - name: deviceId + - name: locationId in: path - description: Device ID for which to upload a map + description: Location ID that contains the source device required: true schema: - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - delete: - summary: Delete Sensitivity Map - operationId: Delete Sensitivity Map - tags: - - Devices - security: - - userApiKey: [] - parameters: + type: integer - name: deviceId in: path - description: Device ID for which to delete a map + description: Device ID acting as a source required: true schema: type: string + - name: simulatedLocationId + in: query + description: Location ID where a simulated devise will be registered + schema: + type: integer responses: '200': - description: OK + description: Simulated device ID content: application/json: schema: @@ -7142,46 +6669,42 @@ paths: properties: resultCode: type: integer + deviceId: + type: string + description: Simulated device ID example: resultCode: 0 + deviceId: SIM1_DEVICE_ID - /cloud/json/devices/{deviceId}/voip: - post: - summary: Register Device VoIP account - operationId: Register VoIP account + /cloud/json/devices/{deviceId}/services: + get: + summary: Get Services by Device + operationId: Get Services by Device description: |- - Some device can make VoIP calls. Before making a call the device should register on a SIP server. - - This functionality is available for specific customers. - - The API will check, if the device supports VoIP calls. - Then it will send a command to the device to register on the SIP server. + A gateway or proxy can request a list of assigned subscription services to the device and the location. + + The `PPCAuthorization` headers may take on one form to identify the source device: + * Using a Device Authentication Token: `PPCAuthorization: esp token="ABC12345"` tags: - Devices - security: - - userApiKey: [] parameters: - name: deviceId in: path - description: Device ID + description: Device ID of the gateway or proxy required: true schema: type: string - - name: locationId - in: query - description: Device location ID + - name: PPCAuthorization + in: header + description: Device's authorization required: true schema: - type: integer - - name: forceCommand - in: query - description: Send the VoIP registration command to the device even it is succesfully registered already. - schema: - type: boolean + type: string + example: esp token=ABC12345 responses: '200': - description: OK + description: Services content: application/json: schema: @@ -7189,34 +6712,71 @@ paths: properties: resultCode: type: integer + services: + type: array + items: + type: object + properties: + name: + type: string + amount: + type: integer + startDate: + type: string + startDateMs: + type: integer + endDate: + type: string + endDateMs: + type: integer + required: + - name + - amount + - startDate + - startDateMs + - endDate + - endDateMs example: resultCode: 0 + services: + - name: Care Pro + amount: 1 + startDate: '2014-05-01T12:00:00Z' + startDateMs: 1398945600000 + endDate: '2014-06-01T12:00:00Z' + endDateMs: 1401624000000 + - name: DeviceFileSpace + amount: 2147483648 + startDate: '2014-05-01T12:00:00Z' + startDateMs: 1398945600000 + endDate: '2014-06-01T12:00:00Z' + endDateMs: 1401624000000 - delete: - summary: Remove device VoIP registration - operationId: Remove VoIP registration + + /cloud/json/locations/{locationId}/deviceActivation/{deviceType}: + get: + summary: Get Device Activation Info + operationId: Get Device Activation Info + description: >- + Some devices require manual interaction to complete registration in the Care Daily AI Platform. + This API returns a device activation key. tags: - Devices security: - userApiKey: [] parameters: - - name: deviceId + - name: locationId in: path - description: Device ID + description: Location ID to register a device required: true schema: - type: string - - name: locationId - in: query - description: Device location ID + type: integer + - name: deviceType + in: path + description: Device type ID required: true schema: type: integer - - name: forceCommand - in: query - description: Send the clear VoIP configuration command to the device - schema: - type: boolean responses: '200': description: OK @@ -7227,15 +6787,18 @@ paths: properties: resultCode: type: integer + deviceActivationKey: + type: string example: resultCode: 0 + deviceActivationKey: "3:20Q9mYSH14s0M4v5o" - /cloud/json/devices/{deviceId}/voipCall: - put: - summary: Make VoIP Call - operationId: Make VoIP Call - description: If the device is registered on a SIP server, it can make a VoIP call. + /cloud/json/devices/{deviceId}/properties: + post: + summary: Set Device Properties + operationId: Set Device Properties + description: A Device Property allows you to associate some extra key/value information with a particular device. Device Property keys and values can be 250 characters maximum. tags: - Devices security: @@ -7244,7 +6807,7 @@ paths: parameters: - name: deviceId in: path - description: Device ID + description: Device ID to set a key/value property for required: true schema: type: string @@ -7254,39 +6817,83 @@ paths: required: true schema: type: integer - - name: sipAddress - in: query - description: SIP address to make a call - schema: - type: string - - name: phone - in: query - description: Phone number to make a call, if SIP address is not provided + requestBody: + content: + application/json: + example: + property: + - name: size + value: '10' + - name: xMin + index: '1' + value: '1.5' + schema: + type: object + properties: + property: + type: array + items: + type: object + properties: + name: + type: string + description: Property name + value: + type: string + description: Property value + index: + type: string + description: Optional property index + required: + - name + - value + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + get: + summary: Get Device Properties + operationId: Get Device Properties + tags: + - Devices + security: + - userApiKey: [] + - botApiKey: [] + parameters: + - name: deviceId + in: path + description: Device ID for which to retrieve device properties + required: true schema: type: string - - name: addressName + - name: locationId in: query - description: SIP address or phone number name to get them from a system property + description: Device location ID + required: true schema: - type: string - - name: audioDeviceId + type: integer + - name: name in: query - description: Audio Device ID, if not set, the first available one will be used + description: Optional name of the property to retrieve schema: type: string - - name: speakerVolume - in: query - description: Audio Device speaker volume - schema: - type: integer - - name: micVolume + - name: index in: query - description: Audio Device microphone volume + description: Optional index value of the property to retrieve schema: - type: integer + type: string responses: '200': - description: OK + description: Properties content: application/json: schema: @@ -7294,13 +6901,37 @@ paths: properties: resultCode: type: integer + properties: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + index: + type: string + required: + - name + - value example: resultCode: 0 + properties: + - name: color + value: white + - name: texture + value: smooth + - name: appliance + index: '0' + value: TV + - name: appliance + index: '1' + value: DVR delete: - summary: Hang Up VoIP Call - operationId: Hang Up VoIP Call - description: Hang up all active VoIP calls on the device. + summary: Delete a Device Property + operationId: Delete a Device Property tags: - Devices security: @@ -7319,6 +6950,17 @@ paths: required: true schema: type: integer + - name: name + in: query + description: Name of the property to delete + required: true + schema: + type: string + - name: index + in: query + description: Optional index value of the property to delete + schema: + type: string responses: '200': description: OK @@ -7333,37 +6975,37 @@ paths: resultCode: 0 - /cloud/json/devices/{deviceId}/parameters: - get: - summary: Get Current Device Measurements - operationId: Get Current Measurements + /cloud/json/locations/{locationId}/devices/{deviceId}/spaces/{spaceId}: + put: + summary: Link Device Space + operationId: Link Space + description: A user can map devices to location spaces. Each device can be linked to one or multiple spaces on the same location based on the device type. tags: - - Device Measurements + - Devices security: - userApiKey: [] parameters: + - name: locationId + in: path + description: Location ID + required: true + schema: + type: integer - name: deviceId in: path - description: Device ID to get parameters from. + description: Device ID required: true schema: type: string - - name: locationId - in: query - description: Request information on a specific location + - name: spaceId + in: path + description: Space ID required: true schema: type: integer - - name: paramName - in: query - description: >- - Optional Parameter name to extract. - You may specify multiple `paramName` URL parameters to gather multiple specific parameters. - schema: - type: string responses: '200': - description: Current device parameters + description: OK content: application/json: schema: @@ -7371,137 +7013,38 @@ paths: properties: resultCode: type: integer - devices: - type: array - items: - type: object - properties: - id: - type: string - lastDataReceivedDate: - type: string - lastDataReceivedDateMs: - type: integer - lastMeasureDate: - type: string - lastMeasureDateMs: - type: integer - parameters: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - lastUpdateTime: - type: string - lastUpdateTimeMs: - type: integer - required: - - name - - lastUpdateTime - - lastUpdateTimeMs example: resultCode: 0 - devices: - - id: ea5101a8005f-10031-470 - lastDataReceivedDate: '2014-06-20T12:47:11-07:00' - lastDataReceivedDateMs: 1403293631000 - lastMeasureDate: '2014-06-20T12:47:11-07:00' - lastMeasureDateMs: 1403293631000 - parameters: - - name: firmware - value: 0.5.4 - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - name: progress - value: '100' - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - name: status - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - put: - summary: Send a Command - operationId: Send a Command - description: |- - A successful result code does not indicate the device executed the command. - Check the device's parameters in a few moments to see if it updated its status. - - | Command Type | Description | - | :----------: | ----------- | - | 0 | Set parameters | - | 4 | Get parameters | - If the device is offline, you will receive an error code 21, "Device is offline or disconnected". + delete: + summary: Unlink Device Space + operationId: Unlink Space tags: - - Device Measurements + - Devices security: - userApiKey: [] parameters: + - name: locationId + in: path + description: Location ID + required: true + schema: + type: integer - name: deviceId in: path - description: Device ID for which to send a command + description: Device ID required: true schema: type: string - - name: locationId - in: query - description: Device location ID + - name: spaceId + in: path + description: Space ID required: true schema: type: integer - requestBody: - content: - application/json: - example: - commandType: 0 - commandTimeout: 15000 - comment: Why this command has been sent - params: - - name: outletStatus - index: '0' - value: '1' - - name: temperature - value: '70' - unit: Degrees F - schema: - type: object - properties: - commandType: - type: integer - description: Optional command type, default is 0 - commandTimeout: - type: integer - description: Optional command timeout in milliseconds from the creation time - comment: - type: string - description: Comment describes, why this command was made - params: - type: array - items: - type: object - properties: - name: - type: string - description: Configured parameter name - index: - type: string - description: Device part index is needed, if the device interprets or expects an index value - value: - type: string - description: New parameter value or value for a specific command or null to request it from the device by the get command - unit: - type: string - description: Unit can be used, if the app needs to use non-system unit for this parameter - required: - - name responses: '200': - description: Executed command details + description: OK content: application/json: schema: @@ -7509,51 +7052,55 @@ paths: properties: resultCode: type: integer - commands: - type: array - items: - type: object - properties: - id: - type: integer - deviceId: - type: string example: resultCode: 0 - commands: - - id: 123 - deviceId: ABC123 - /cloud/json/parameters: + /cloud/json/fwupdate: get: - summary: Get Current Measurements for Multiple Devices - operationId: Get Measurements for Multiple Devices - description: '' + summary: Get Firmware Jobs + operationId: Get Firmware Jobs + description: |- + A user can approve or decline an update of his devices with new firmware. + + Frimware update job statuses: + + | Status | Description | + | :----: | ----------- | + | 1 | Available | + | 2 | Approved | + | 3 | Decline | + | 4 | Started | + + This API allows to retrieve a list of available firmware updates for user devices. tags: - - Device Measurements + - Devices security: - userApiKey: [] parameters: - - name: locationId + - name: deviceId in: query - description: Location ID - required: true + description: Optional filter by device ID schema: - type: integer - - name: deviceId + type: string + - name: index in: query - description: Device ID's search field to extract parameters from. Multiple values supported. + description: Check update for specific device part schema: type: string - - name: paramName + - name: firmware in: query - description: Parameter names to extract. Multiple values supported. + description: Current device firmware version schema: type: string + - name: userId + in: query + description: Device owner ID for access by an administrator + schema: + type: integer responses: '200': - description: Current Device Parameters + description: Firmware update jobs content: application/json: schema: @@ -7561,162 +7108,126 @@ paths: properties: resultCode: type: integer - devices: + jobs: type: array items: type: object properties: id: + type: integer + description: Job ID + index: type: string - lastDataReceivedDate: + description: Optional device part to update + firmware: type: string - lastDataReceivedDateMs: + description: New firmware version + currentFirmware: + type: string + description: Current firmware version + status: type: integer - lastMeasureDate: + description: Update status + forced: + type: boolean + description: No user's approval required + url: type: string - lastMeasureDateMs: + description: Firmware downloca URL + checkSum: + type: string + description: Firmware checksum + notificationDate: + type: string + description: Last user's notification date about the available update + notificationDateMs: type: integer - parameters: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - lastUpdateTime: - type: string - lastUpdateTimeMs: - type: integer - index: - type: string - required: - - name - - lastUpdateTime - - lastUpdateTimeMs - required: - - id - - lastDataReceivedDate - - lastMeasureDate - - parameters + startDate: + type: string + description: Update start date + startDateMs: + type: integer + device: + type: object + description: Updated device properties + properties: + id: + type: string + type: + type: integer + typeCategory: + type: integer + desc: + type: string + lastDataReceivedDate: + type: string + lastDataReceivedDateMs: + type: integer example: resultCode: 0 - devices: - - id: ea5101a8005f-10031-470 - lastDataReceivedDate: '2014-06-20T12:47:11-07:00' - lastDataReceivedDateMs: 1403293631000 - lastMeasureDate: '2014-06-20T12:47:11-07:00' - lastMeasureDateMs: 1403293631000 - parameters: - - name: firmware - value: 0.5.4 - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - name: progress - value: '100' - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - name: status - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - id: moss-outlet - lastDataReceivedDate: '2014-06-20T12:47:11-07:00' - lastMeasureDate: '2014-06-20T12:47:11-07:00' - parameters: - - name: model - value: Hello World! - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - name: outletStatus - index: '0' - value: 'ON' - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - - name: power - index: '0' - value: '10' - lastUpdateTime: '2014-06-20T12:47:11-07:00' - lastUpdateTimeMs: 1403293631000 - + jobs: + - id: 123 + index: BLE + firmware: 1.4.5 + currentFirmware: 1.2.3 + status: 2 + forced: false + url: https://fw.peoplepowerco.com/update_1_0_10.apk + checkSum: 391bd1de48e2539ea2a9795365a313046238e2b8c88fd6b8d4fbb113dbf93085 + notificationDate: '2014-06-20T12:47:11-07:00' + notificationDateMs: 1403293631000 + startDate: '2014-06-20T12:47:11-07:00' + startDateMs: 1403293631000 + device: + id: GATEWAY_ID + type: 31 + typeCategory: 18000 + desc: Gateway + lastDataReceivedDate: '2014-12-26T02:31:09-05:00' + lastDataReceivedDateMs: 1419579069000 put: - summary: Send Commands - operationId: Send Commands + summary: Set Firmware Update Status + operationId: Set Firmware Update Status description: |- - This API allows to send commands to multiple devices simultaneously. + Approve or decline a not forced firmware update job. - This operation is not atomic. It will try to execute all commands in the same order, as they are provided. - If some command fails, it will execute the next one. The result code is returned for each command. + The user can schedule the update after specific date and time. tags: - - Device Measurements + - Devices security: - userApiKey: [] parameters: - - name: locationId + - name: deviceId in: query - description: Devices location ID + description: Device ID + required: true + schema: + type: string + - name: status + in: query + description: New job status:
2 - approved
3 - declined required: true schema: type: integer - requestBody: - content: - application/json: - example: - devices: - - deviceId: ABC123 - commandType: 0 - commandTimeout: 15000 - params: - - name: outletStatus - index: '0' - value: '1' - - name: ppc.lowPowerMode - value: '0' - comment: Why this command has been sent - schema: - type: object - properties: - devices: - type: array - items: - type: object - properties: - deviceId: - type: string - description: Device ID - commandType: - type: integer - description: Optional command type, default is 0 - commandTimeout: - type: integer - description: Optional command timeout in milliseconds from the creation time - comment: - type: string - description: Comment describes, why this command was made - params: - type: array - items: - type: object - properties: - name: - type: string - description: Configured parameter name - index: - type: string - description: Device part index is needed, if the device interprets or expects an index value - value: - type: string - description: New parameter value or value for a specific command or null to request it from the device by the get command - unit: - type: string - description: Unit can be used, if the app needs to use non-system unit for this parameter - required: - - name - required: - - deviceId + enum: [2,3] + - name: index + in: query + description: Update firmware of specific device part + schema: + type: string + - name: startDate + in: query + description: Firmware update start date + schema: + type: string + - name: userId + in: query + description: Device owner ID for access by an administrator + schema: + type: integer responses: '200': - description: Commands execution results + description: OK content: application/json: schema: @@ -7724,109 +7235,44 @@ paths: properties: resultCode: type: integer - commands: - type: array - items: - type: object - properties: - id: - type: integer - deviceId: - type: string - resultCode: - type: integer - resultCodeMessage: - type: string example: resultCode: 0 - commands: - - id: 123 - deviceId: ABC123 - resultCode: 0 - resultCodeMessage: Error message - /cloud/json/devices/{deviceId}/parametersByDate/{startDate}: + /cloud/json/deviceLogs: get: - summary: Get History of Measurements - operationId: Get History of Measurements + summary: Get Device Logs + operationId: Get Device Logs + description: Returns a list device log files stored in the system tags: - - Device Measurements + - Devices security: - userApiKey: [] parameters: - - name: deviceId - in: path - description: Device ID for which to get a history of measurements - required: true - schema: - type: string - name: locationId in: query - description: Location ID + description: Request device on a specific location required: true schema: type: integer - - name: startDate - in: path - description: Start date to begin receiving measurements, for example 2014-08-01T12:00:00-08:00 - required: true - schema: - type: string - - name: endDate - in: query - description: >- - End date to stop receiving measurements, for example 2014-08-01T13:00:00-08:00. - Default is the current date. - schema: - type: string - - name: paramName + - name: deviceId in: query - description: Only obtain measurements for given parameter names. Multiple values can be passed. + description: Device ID filter schema: type: string - - name: index + - name: startDate in: query - description: Only obtain measurements for parameters with this index value + description: Limit response by date, 30 days in the past maximum schema: type: string - - name: rangeOnly - in: query - description: Return parameters stored exactly between start and end dates - schema: - type: boolean - - name: reduceNoise - in: query - description: Return tiny parameter values less than defined threshold as zero - schema: - type: boolean - - name: interval - in: query - description: Aggregate the readings by this interval, in minutes - schema: - type: integer - - name: aggregation - in: query - description: |- - Interval aggregation algorithm: -
0 = last value before the interval point - default -
1 = minimum value -
2 = maximum value -
3 = median value -
4 = time distributed average value -
5 = average value - schema: - type: integer - enum: [0,1,2,3,4,5] - - name: sortOrder + - name: endDate in: query - description: Order result by timestamp
asc = ascending
desc = descending + description: Limit response by date schema: type: string - enum: [asc,desc] responses: '200': - description: Measurements history + description: Device logs content: application/json: schema: @@ -7834,115 +7280,68 @@ paths: properties: resultCode: type: integer - readings: + logs: type: array items: type: object properties: deviceId: type: string - timeStamp: + logDate: type: string - timeStampMs: + logDateMs: type: integer - params: - type: array - items: - type: object - properties: - name: - type: string - index: - type: string - value: - type: string - required: - - name - required: - - deviceId - - timeStamp - - timeStampMs - - params + size: + type: integer + contentType: + type: string + logType: + type: string + logName: + type: string example: resultCode: 0 - readings: - - deviceId: MON9648 - timeStamp: '2014-12-21T00:58:49-04:00' - timeStampMs: 1419137929000 - params: - - name: power - value: '865' - - name: energy - value: '0.003' - - deviceId: MON9648 - timeStamp: '2014-12-21T00:58:49-04:00' - timeStampMs: 1419137929000 - params: - - name: energy - value: '0.004' + logs: + - deviceId: DEVICE_ID + logDate: '2021-09-20T12:47:11-07:00' + logDateMs: 1603293631000 + size: 10000 + contentType: application/octet-stream + logType: logs + logName: '1603293631000' - /cloud/json/devices/{deviceId}/parametersByCount/{rowCount}: + /cloud/json/deviceLogContent: get: - summary: Get the Last N Measurements - operationId: Get the Last N Measurements - description: >- - The first timestamp reading will contain all measured parameters and their values. - All other timestamp readings will only contain the parameters that changed in value. + summary: Get Device Log Content + operationId: Get Device Log Content + description: This API returns a temporary URL to download log's content. tags: - - Device Measurements + - Devices security: - userApiKey: [] parameters: - - name: deviceId - in: path - description: Device ID for which to obtain measurements - required: true - schema: - type: string - name: locationId in: query - description: Location ID - required: true - schema: - type: integer - - name: rowCount - in: path - description: Maximum number of measurements to obtain + description: Request device on a specific location required: true schema: type: integer - - name: startDate + - name: deviceId in: query - description: Start date to begin receiving measurements, for example 2014-08-01T12:00:00-08:00 + description: Device ID required: true schema: type: string - - name: endDate - in: query - description: >- - End date to stop receiving measurements, for example 2014-08-01T13:00:00-08:00. - Default is the current date. - schema: - type: string - - name: paramName - in: query - description: Only obtain measurements for given parameter names. Multiple values can be passed. - schema: - type: string - - name: index + - name: logDate in: query - description: Only obtain measurements for parameters with this index value. + description: Log date + required: true schema: type: string - - name: reduceNoise - in: query - description: Return tiny parameter values less than defined threshold as zero - schema: - type: boolean responses: '200': - description: Measurements history + description: Log's content URL content: application/json: schema: @@ -7950,85 +7349,146 @@ paths: properties: resultCode: type: integer - readings: - type: array - items: - type: object - properties: - deviceId: - type: string - timeStamp: - type: string - timeStampMs: - type: integer - params: - type: array - items: - type: object - properties: - name: - type: string - index: - type: string - value: - type: string - required: - - name + url: + type: string example: resultCode: 0 - readings: - - deviceId: ea5101a8005f-10031-470 - timeStamp: '2014-08-01T13:00:00-08:00' - timeStampMs: 1419137929000 - params: - - name: status - value: Accepting new devices - - name: progress - value: '100' + url: https://s3.amazon.com/logs/abc123?param=value - /cloud/json/alerts: - get: - summary: Get History of Device Alerts - operationId: Get History of Alerts - description: '' + /cloud/json/devices/{deviceId}/sensitivityMap: + post: + summary: Upload Sensitivity Map + operationId: Upload Sensitivity Map + description: >- + The sensitivity map content must be uploaded as octet-stream. + The API will send a command to the device to download the map. tags: - - Device Measurements + - Devices security: - userApiKey: [] parameters: - name: deviceId - in: query - description: Device ID for which to get a history of alerts + in: path + description: Device ID for which to upload a map + required: true + schema: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + delete: + summary: Delete Sensitivity Map + operationId: Delete Sensitivity Map + tags: + - Devices + security: + - userApiKey: [] + parameters: + - name: deviceId + in: path + description: Device ID for which to delete a map + required: true + schema: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + + /cloud/json/devices/{deviceId}/voip: + post: + summary: Register Device VoIP account + operationId: Register VoIP account + description: |- + Some device can make VoIP calls. Before making a call the device should register on a SIP server. + + This functionality is available for specific customers. + + The API will check, if the device supports VoIP calls. + Then it will send a command to the device to register on the SIP server. + tags: + - Devices + security: + - userApiKey: [] + parameters: + - name: deviceId + in: path + description: Device ID + required: true schema: type: string - name: locationId in: query - description: Location ID + description: Device location ID required: true schema: type: integer - - name: alertType + - name: forceCommand in: query - description: Retrieve only alerts of this type + description: Send the VoIP registration command to the device even it is succesfully registered already. + schema: + type: boolean + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + delete: + summary: Remove device VoIP registration + operationId: Remove VoIP registration + tags: + - Devices + security: + - userApiKey: [] + parameters: + - name: deviceId + in: path + description: Device ID + required: true schema: type: string - - name: startDate + - name: locationId in: query - description: Start date to begin receiving alerts, for example 2014-08-01T12:00:00-08:00 + description: Device location ID required: true schema: - type: string - - name: endDate + type: integer + - name: forceCommand in: query - description: >- - End date to stop receiving alerts, for example 2014-08-01T13:00:00-08:00. - Default is the current date. + description: Send the clear VoIP configuration command to the device schema: - type: string + type: boolean responses: '200': - description: Device alerts history + description: OK content: application/json: schema: @@ -8036,180 +7496,63 @@ paths: properties: resultCode: type: integer - alerts: - type: array - items: - type: object - properties: - deviceId: - type: string - alertType: - type: string - receivingDate: - type: string - receivingDateMs: - type: integer - params: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - required: - - name - - value - required: - - deviceId - - alertType - - receivingDate - - receivingDateMs example: resultCode: 0 - alerts: - - deviceId: MON9648 - alertType: motion - receivingDate: '2014-12-21T00:58:49-04:00' - receivingDateMs: 1419137929000 - params: - - name: fileRef - value: '865' - - name: count - value: '10' - - /cloud/json/dataRequests: - post: - summary: Submit Data Request - operationId: Submit Data Request - description: |- - Selecting large amount of data from the database can take significant time. - To avoid this long waiting period a user can submit requests for all data to the server asynchronously. - When the requests will be completed, the user will be notified by email. - Selected data will be uploaded to S3 in CSV format (compressed) and stored for one day. - Links to download the data files will be sent by email by the user's request. - Otherwise, they can be received by calling the get data API. - - Following data types are available for requesting: - - | Type | Details | - | :--: | :------ | - | 1 | Device parameters history | - | 2 | Device activities history | - | 3 | Organization locations | - | 4 | Location modes history | - | 5 | Location narratives | - | 6 | Organization devices | - | 7 | Data streams | - | 8 | Energy usage | - | 9 | Device alerts history | - | 10 | Location Time States | + /cloud/json/devices/{deviceId}/voipCall: + put: + summary: Make VoIP Call + operationId: Make VoIP Call + description: If the device is registered on a SIP server, it can make a VoIP call. tags: - - Device Measurements + - Devices security: - userApiKey: [] + - botApiKey: [] parameters: + - name: deviceId + in: path + description: Device ID + required: true + schema: + type: string - name: locationId in: query - description: Request information from specific location + description: Device location ID + required: true + schema: + type: integer + - name: sipAddress + in: query + description: SIP address to make a call + schema: + type: string + - name: phone + in: query + description: Phone number to make a call, if SIP address is not provided + schema: + type: string + - name: addressName + in: query + description: SIP address or phone number name to get them from a system property + schema: + type: string + - name: audioDeviceId + in: query + description: Audio Device ID, if not set, the first available one will be used + schema: + type: string + - name: speakerVolume + in: query + description: Audio Device speaker volume + schema: + type: integer + - name: micVolume + in: query + description: Audio Device microphone volume schema: type: integer - requestBody: - content: - application/json: - example: - brand: care - byEmail: true - dataRequests: - - type: 1 - key: Front door history - deviceId: ABC123 - startTime: 1446537883000 - endTime: 1456537883000 - paramNames: - - doorStatus - index: '0' - ordered: 1 - compression: 1 - schema: - type: object - properties: - brand: - type: string - description: Notification brand - byEmail: - type: boolean - description: Notify the user by email, when the request completed. - dataRequests: - type: array - description: Data requests - items: - type: object - properties: - type: - type: integer - enum: [1,2,3,4,5,6,7,8,9,10] - description: Data type - key: - type: string - description: Optional request key - deviceId: - type: string - description: Device ID required for data types 1,2,8,9 - startTime: - type: integer - description: Period start time in milliseconds required for data types 1,2,5,7,8,9,10 - endTime: - type: integer - description: Period end time in milliseconds required for data types 1,2,5,7,8,9,10 - paramNames: - type: array - description: Device parameter names optional for data type 1 - items: - type: string - index: - type: string - description: Device part index optional for data type 1 - organizationId: - type: integer - description: Organization ID required for data types 3,6,10 - searchBy: - type: string - description: Search string optional for data type 3. Use '*' for wildcard. - locationTags: - type: array - description: Location search tags optional for data type 3 - items: - type: string - deviceTags: - type: array - description: Device search tags optional for data type 3 - items: - type: string - deviceTypes: - type: array - description: Device search types optional for data types 3,6 - items: - type: integer - names: - type: array - description: Location state names required for the data type 10 - items: - type: string - aggregation: - type: integer - description: Data aggregation by:
0 = None
1 = Hours
2 = Days
3 = Months
4 = 7-day weeks
5 = 5-day weeks
required for data type 8 - ordered: - type: integer - description: Order data by timestamp
1 = ASC
-1 = DESC
optional for data types 1,2,4,5,9 - compression: - type: integer - description: Data compression
0 = LZ4, default
1 = ZIP
2 = none - required: - - type responses: '200': description: OK @@ -8223,33 +7566,31 @@ paths: example: resultCode: 0 - get: - summary: Get Requested Data - operationId: Get Requested Data - description: Completed data requests can be retrieved by calling this API. + delete: + summary: Hang Up VoIP Call + operationId: Hang Up VoIP Call + description: Hang up all active VoIP calls on the device. tags: - - Device Measurements + - Devices security: - userApiKey: [] + - botApiKey: [] parameters: - - name: locationId - in: query - description: Location ID + - name: deviceId + in: path + description: Device ID + required: true schema: - type: integer - - name: organizationId + type: string + - name: locationId in: query - description: Organization ID + description: Device location ID + required: true schema: type: integer - - name: requestKey - in: query - description: Filter by data request key - schema: - type: string responses: '200': - description: Data requests history + description: OK content: application/json: schema: @@ -8257,70 +7598,41 @@ paths: properties: resultCode: type: integer - results: - type: array - items: - type: object - properties: - type: - type: integer - description: Data request type - key: - type: string - description: Request key - url: - type: string - description: Data download URL - completionDate: - type: string - description: Request completion date - completionDateMs: - type: integer - expiryDate: - type: string - description: Data URL expiry date - expiryDateMs: - type: integer - deviceId: - type: string - description: Requested data device ID - startDate: - type: string - description: Requested data start date - startDateMs: - type: integer - endDate: - type: string - description: Requested data end date - endDateMs: - type: integer example: resultCode: 0 - results: - - type: 1 - key: Front door history - url: >- - https://s3.amazonaws.com/bucket/fileId?X-Amz-Algorithm=AWS4-HMAC-SHA256 - completionDate: '2019-04-08T12:13:14Z' - completionDateMs: 1456537883000 - expiryDate: '2019-04-09T12:13:14Z' - expiryDateMs: 1456557883000 - deviceId: ABC123 - startDate: '2010-01-01T00:00:00Z' - startDateMs: 1446537883000 - endDate: '2020-01-01T00:00:00Z' - endDateMs: 1646537883000 - /cloud/json/units: + /cloud/json/devices/{deviceId}/parameters: get: - summary: Get Units of Measurement - operationId: Get Units of Measurement + summary: Get Current Device Measurements + operationId: Get Current Measurements tags: - Device Measurements + security: + - userApiKey: [] + parameters: + - name: deviceId + in: path + description: Device ID to get parameters from. + required: true + schema: + type: string + - name: locationId + in: query + description: Request information on a specific location + required: true + schema: + type: integer + - name: paramName + in: query + description: >- + Optional Parameter name to extract. + You may specify multiple `paramName` URL parameters to gather multiple specific parameters. + schema: + type: string responses: '200': - description: Device Parameter Units + description: Current device parameters content: application/json: schema: @@ -8328,515 +7640,137 @@ paths: properties: resultCode: type: integer - units: + devices: type: array items: type: object properties: - unit: + id: type: string - description: + lastDataReceivedDate: type: string - required: - - unit - - description - example: - resultCode: 0 - units: - - unit: A - description: Current Ampere - - unit: A/A - description: Ratio of amperages, A/A - - unit: A/m - description: Magnetic field strength (A/m) - - unit: A^2 - description: Amps squared (A?) - - unit: A^2h - description: Ampere-squared hour (A^2h) - - unit: A^2s - description: Ampere-squared second (A^2s) - - unit: Ah - description: Ampere-hours - - unit: As - description: Amp seconds - - unit: B - description: Sound pressure level, Bel. Combine with multiplier prefix 'd' to form decibels of Sound Pressure Level 'dB' - - unit: Bm - description: Signal Strength, Bel-mW, normalized to 1mW. To form 'dBm', combine 'Bm' with multiplier 'd'. - - unit: Bq - description: Radioactivity (l/s) - - unit: C - description: Electric charge (AS) - - unit: F - description: Electric capacitance (C/V) - - unit: Gy - description: Absorbed dose (J/kg) - - unit: H - description: Electric inductance (Wb/A) - - unit: Hz - description: Frequency hertz (1/s) - - unit: Hz/Hz - description: Rate of change of frequency - - unit: Hz/s - description: Rate of change of frequency - - unit: J - description: Energy joule (N m) - - unit: J/K - description: Heat capacity - - unit: J/kg - description: Joules per kilogram - - unit: J/m^2 - description: Solar radiation - - unit: K - description: Absolute Temperature - - unit: L - description: Litre - - unit: L/L - description: Concentration, The ratio of the volume of a solute divided by the volume of the solution., L/L - - unit: L/h - description: Litres per hour - - unit: L/s - description: Volumetric flow rate, Volumetric flow rate, L/s - - unit: Lm - description: Luminous flux (cd sr) - - unit: 'N' - description: Force newton (kg m/s^2) - - unit: Pa - description: Pressure (N/m?) - - unit: PaA - description: Pressure, Pascal, absolute pressure, PaA - - unit: PaG - description: Pressure, Pascal, gauge pressure, PaG - - unit: Q - description: Quantity power - - unit: Qh - description: Quantity energy - - unit: Siemens - description: Electric conductance (A/V) - - unit: Sv - description: Dose equivalent (J/kg) - - unit: T - description: Magnetic flux density (Wb/m^2) - - unit: V - description: Electric potential (W/A) - - unit: V/Hz - description: Magnetic flux - - unit: V/V - description: Voltage, Ratio of voltages (e.g. mV/V), V/V - - unit: VA - description: Apparant power (VA) - - unit: VAh - description: Apparant energy - - unit: VAh/rev - description: Kh-Vah, apparent energy metering constant, VAh/rev - - unit: VAr - description: Reactive power (Volt Ampere reactive (VI Sin Theta)) - - unit: VArh - description: Reactive energy - - unit: VArh/rev - description: Kh-VArh, reactive energy metering constant, VArh/rev - - unit: V^2 - description: Volts squared (W^2/A?^2 - - unit: V^2h - description: Volt-squared hour (V^2h) - - unit: Vs - description: Volt seconds (Ws/A) - - unit: W - description: Real power (I^2R) - - unit: W/W - description: Signal Strength, Ratio of power, W/W - - unit: W/m K - description: Thermal conductivity - - unit: W/s - description: Watts per second - - unit: Wb - description: Magnetic flux (V s) - - unit: Wh - description: Real energy - - unit: Wh/m^3 - description: Energy per volume (Wh/m^3) - - unit: Wh/rev - description: Kh-Wh, active energy metering constant, Wh/rev - - unit: boolean - description: Boolean (0 or 1) - - unit: btu - description: British Thermal Units - - unit: btu/h - description: British Thermal Units per hour - - unit: cd - description: Luminous intensity - - unit: char - description: Number of characters - - unit: char/s - description: Data rate - - unit: count - description: Counter Value (0, 1, 2, 3, 4, ...) - - unit: deg - description: Plane angle - - unit: degrees C - description: Relative Temperature in Celsius - - unit: degrees F - description: Relative Temperature in Fahrenheit - - unit: degrees Theta - description: Phase angle - - unit: ft^3 - description: Volume, cubic feet - - unit: ft^3/h - description: Cubic feet per hour - - unit: g - description: Mass - - unit: g/kg - description: Ratio of mass - - unit: gM2 - description: Turbine inertia, gram*meter2 (Combine with multiplier prefix 'k' to form kg*m2.) - - unit: gPerG - description: Concentration, The ratio of the mass of a solute divided by the mass of the solution., g/g - - unit: gif - description: GIF image - - unit: hour - description: Hour - - unit: imperialGal - description: Volume, imperial gallons, ImperialGal - - unit: imperialGalPerH - description: Volumetric flow rate, Imperial gallons per hour, ImperialGal/h - - unit: int - description: Generic Int - - unit: jpg - description: JPEG Image - - unit: json - description: JSON object - - unit: kat - description: Catalytic activity, katal = mol / s, kat - - unit: kg/m^3 - description: Density - - unit: kgM - description: Moment of mass, kilogram meter (kg*m), M - - unit: lx - description: Illuminance lux (lm/m^2) - - unit: m - description: Length - - unit: m/m - description: Length, Ratio of length, m/m - - unit: m/m^3 - description: Fuel efficiency (m/m^3) - - unit: m/s - description: Velocity - - unit: m/s^2 - description: Acceleration - - unit: m^2 - description: Area - - unit: m^2/s - description: Viscosity - - unit: m^3 - description: Volume - - unit: m^3/h - description: Volumetric flow rate (m^3/s) - - unit: m^3/s - description: Volumetric flow rate (m^3/s) - - unit: minute - description: Minute - - unit: mol - description: Amount of Substance - - unit: mol/kg - description: Concentration, Molality, the amount of solute in moles and the amount of solvent in kilograms., mol/kg - - unit: mol/m^3 - description: >- - Concentration, The amount of substance concentration, (c), - the amount of solvent in moles divided by the volume of solution in m^3, mol/m^3 - - unit: mol/mol - description: >- - Concentration, Molar fraction, the ratio of the molar - amount of a solute divided by the molar amount of the solution.,mol/mol - - unit: money - description: Money - - unit: ohm - description: Electric resistance (VA) - - unit: pf - description: Power factor (dimensionless, Cos Phi) - - unit: ppm - description: Concentration - - unit: psiA - description: Pressure, Pounds per square inch, absolute, psiA - - unit: psiG - description: Pressure, Pounds per square inch, gauge, psiG - - unit: q45 - description: Quantity power, Q measured at 45º, Q45 - - unit: q45h - description: Quantity energy, Q measured at 45º, Q45h - - unit: q60 - description: Quantity power, Q measured at 60º, Q60 - - unit: q60h - description: Quantity energy, Qh measured at 60º, Q60h - - unit: rad - description: Plane angle - - unit: rad/s - description: Angular velocity - - unit: relativeHumidity - description: >- - Relative humidity, the ratio of partial pressure of water - vapor in the air-water mixture to the saturated vapor - pressure of water at those conditions - - unit: rev - description: Amount of rotation, Revolutions, rev - - unit: rev/s - description: Rotational Speed - - unit: rho - description: Resistivity (rho) (Ohm) - - unit: s - description: Time (seconds) - - unit: s/s - description: >- - Time, Ratio of time (can be combined with an multiplier - prefix to show rates such as a clock drift rate, e.g. 's/s'), s/s - - unit: specificHumidity - description: >- - Specific humidity is expressed as a ratio of mass of water - vapor per unit mass of dry air - - unit: sr - description: Solid angle - - unit: string - description: Generic text string - - unit: therm - description: Energy, Therm, therm - - unit: timestamp - description: Timestamp (ISO 8601) - - unit: usGal - description: Volume, US gallons, Gal - - unit: usGal/h - description: Volumetric flow rate, US gallons per hour, USGal/h - - unit: version - description: Generic version number - - unit: zipCode - description: Zip / Territory / Postal Code - - - /cloud/json/notificationSubscriptions: - get: - summary: Get Notification Subscriptions - operationId: Get Notification Subscriptions - tags: - - User Communications - description: |- - A user may subscribe or unsubscribe from certain types of push and email notifications, - or set boundaries on how many notifications their account can receive within a specified amount of time. - - The Care Daily AI Platform supports following notification types: - - | Type | Description | Transport | Configurable | Location | - | :--: | ----------- | :-------: | :----------: | :------: | - | 0 | Unsubscribe from all | Email Push SMS | * | | - | 1 | Marketing emails | Email | * | | - | 3 | Rules| Email Push | | | - | 4 | Bots | Email Push SMS | * | * | - | 7 | Device alerts | Email Push | * | * | - | 8 | Apps | Email Push | * | * | - | 11 | Account issues | Push | | | - | 13 | OAuth client | Email Push | * | * | - | 16 | Device firmware update | Push | | | - | 17 | SMS chat | Push SMS | | | - | 18 | Location messages | SMS | | | - | 19 | Bot errors to developers | Email | * | | - | 20 | App badge change | Push | | | - | 22 | Bot reports | Email Push SMS | * | * | - | 23 | Messages | Email Push SMS | * | * | - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: userId - in: query - description: User ID for bots and administrators - schema: - type: integer - responses: - '200': - description: Notification Subscriptions - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - subscriptions: - type: array - items: - type: object - properties: - type: + lastDataReceivedDateMs: type: integer - description: Notification type - name: + lastMeasureDate: type: string - description: Notification type name - locationId: - type: integer - description: Subscription related location ID - email: - type: boolean - description: Notifications by email enabled - push: - type: boolean - description: Push notifications enabled - sms: - type: boolean - description: Notifications by SMS enabled - emailPeriod: - type: integer - description: How long to wait between emails in seconds - pushPeriod: + lastMeasureDateMs: type: integer - description: How long to wait between push notifications in seconds - required: - - type - - email - - push - - sms + parameters: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + lastUpdateTime: + type: string + lastUpdateTimeMs: + type: integer + required: + - name + - lastUpdateTime + - lastUpdateTimeMs example: resultCode: 0 - subscriptions: - - type: 0 - locationId: 0 - email: true - push: true - sms: false - name: All - emailPeriod: 0 - pushPeriod: 0 - - type: 6 - locationId: 0 - email: false - push: false - sms: false - name: Registration follow up - emailPeriod: 0 - pushPeriod: 0 - - type: 7 - locationId: 123 - email: true - push: true - sms: false - name: Device alerts - emailPeriod: 0 - pushPeriod: 0 - - type: 8 - locationId: 123 - email: true - push: true - sms: false - name: Analytics and external - emailPeriod: 0 - pushPeriod: 0 - + devices: + - id: ea5101a8005f-10031-470 + lastDataReceivedDate: '2014-06-20T12:47:11-07:00' + lastDataReceivedDateMs: 1403293631000 + lastMeasureDate: '2014-06-20T12:47:11-07:00' + lastMeasureDateMs: 1403293631000 + parameters: + - name: firmware + value: 0.5.4 + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 + - name: progress + value: '100' + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 + - name: status + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 - /cloud/json/notificationSubscriptions/{type}: put: - summary: Set Notification Subscriptions - operationId: Set Notification Subscriptions - description: '' - tags: - - User Communications - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: type - in: path - description: Type of notification, as defined by the Care Daily AI Platform during the request to Get Subscription Notifications. - required: true - schema: - type: integer - - name: userId - in: query - description: User ID for bots and administrators - schema: - type: integer - - name: locationId - in: query - description: Location ID - schema: - type: integer - - name: email - in: query - description: >- - true - Email notifications enabled -
false - No email notifications - schema: - type: boolean - - name: push - in: query - description: >- - true - Push notifications enabled -
false - No push notifications - schema: - type: boolean - - name: sms - in: query - description: >- - true - SMS notifications enabled -
false - No SMS notifications - schema: - type: boolean - - name: emailPeriod - in: query - description: Minimum number of seconds between email notifications - schema: - type: integer - - name: pushPeriod - in: query - description: Minimum number of seconds between push notifications - schema: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 + summary: Send a Command + operationId: Send a Command + description: |- + A successful result code does not indicate the device executed the command. + Check the device's parameters in a few moments to see if it updated its status. + | Command Type | Description | + | :----------: | ----------- | + | 0 | Set parameters | + | 4 | Get parameters | - /cloud/json/notificationToken/{appName}/{token}: - put: - summary: Register App for Push Notifications - operationId: Register App for Push Notifications + If the device is offline, you will receive an error code 21, "Device is offline or disconnected". tags: - - User Communications + - Device Measurements security: - userApiKey: [] parameters: - - name: appName - in: path - description: Unique App Name to register for push notifications - required: true - schema: - type: string - - name: token + - name: deviceId in: path - description: The iOS notification token or the Android device registration ID + description: Device ID for which to send a command required: true schema: type: string - - name: badge - in: query - description: >- - true - This app supports badge icons -
false - This app does not support badge icons, default - schema: - type: boolean - - name: brand + - name: locationId in: query - description: If set, the app will not receive notifications addressed to different brands + description: Device location ID + required: true schema: - type: string + type: integer + requestBody: + content: + application/json: + example: + commandType: 0 + commandTimeout: 15000 + comment: Why this command has been sent + params: + - name: outletStatus + index: '0' + value: '1' + - name: temperature + value: '70' + unit: Degrees F + schema: + type: object + properties: + commandType: + type: integer + description: Optional command type, default is 0 + commandTimeout: + type: integer + description: Optional command timeout in milliseconds from the creation time + comment: + type: string + description: Comment describes, why this command was made + params: + type: array + items: + type: object + properties: + name: + type: string + description: Configured parameter name + index: + type: string + description: Device part index is needed, if the device interprets or expects an index value + value: + type: string + description: New parameter value or value for a specific command or null to request it from the device by the get command + unit: + type: string + description: Unit can be used, if the app needs to use non-system unit for this parameter + required: + - name responses: '200': - description: OK + description: Executed command details content: application/json: schema: @@ -8844,28 +7778,51 @@ paths: properties: resultCode: type: integer + commands: + type: array + items: + type: object + properties: + id: + type: integer + deviceId: + type: string example: resultCode: 0 + commands: + - id: 123 + deviceId: ABC123 - /cloud/json/notificationToken/{token}: - delete: - summary: Unregister App for Push Notifications - operationId: Unregister App for Push Notifications + /cloud/json/parameters: + get: + summary: Get Current Measurements for Multiple Devices + operationId: Get Measurements for Multiple Devices + description: '' tags: - - User Communications + - Device Measurements security: - userApiKey: [] parameters: - - name: token - in: path - description: The iOS notification token or the Android device registration ID + - name: locationId + in: query + description: Location ID required: true + schema: + type: integer + - name: deviceId + in: query + description: Device ID's search field to extract parameters from. Multiple values supported. + schema: + type: string + - name: paramName + in: query + description: Parameter names to extract. Multiple values supported. schema: type: string responses: '200': - description: OK + description: Current Device Parameters content: application/json: schema: @@ -8873,283 +7830,162 @@ paths: properties: resultCode: type: integer + devices: + type: array + items: + type: object + properties: + id: + type: string + lastDataReceivedDate: + type: string + lastDataReceivedDateMs: + type: integer + lastMeasureDate: + type: string + lastMeasureDateMs: + type: integer + parameters: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + lastUpdateTime: + type: string + lastUpdateTimeMs: + type: integer + index: + type: string + required: + - name + - lastUpdateTime + - lastUpdateTimeMs + required: + - id + - lastDataReceivedDate + - lastMeasureDate + - parameters example: resultCode: 0 + devices: + - id: ea5101a8005f-10031-470 + lastDataReceivedDate: '2014-06-20T12:47:11-07:00' + lastDataReceivedDateMs: 1403293631000 + lastMeasureDate: '2014-06-20T12:47:11-07:00' + lastMeasureDateMs: 1403293631000 + parameters: + - name: firmware + value: 0.5.4 + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 + - name: progress + value: '100' + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 + - name: status + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 + - id: moss-outlet + lastDataReceivedDate: '2014-06-20T12:47:11-07:00' + lastMeasureDate: '2014-06-20T12:47:11-07:00' + parameters: + - name: model + value: Hello World! + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 + - name: outletStatus + index: '0' + value: 'ON' + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 + - name: power + index: '0' + value: '10' + lastUpdateTime: '2014-06-20T12:47:11-07:00' + lastUpdateTimeMs: 1403293631000 - - /cloud/json/notifications: - post: - summary: Send a Notification - operationId: Send a Notification + put: + summary: Send Commands + operationId: Send Commands description: |- - Sends an arbitrary push notification or email to the user. - If you're sending an email, you may include a subject and specify whether the email is in HTML format or plain text. - Push notification messages are limited by the standard push notification payload size. - - This API allows to include inline graphics as an attachment. - - Attached content can be set directly. In this case all attachment fields are mandatory. The content field contains the Base64 encoded binary image content. - - Or a device file thumbnail can be used as the content. In this case all other fields are optional. - - The generated by the app email content or the template should include correct references to inline graphics content ID's with "cid:" prefixes. - For example ``. + This API allows to send commands to multiple devices simultaneously. - Location users to notify can be selected by userCategories or user ID's provided in the request body. - - Notification types: - - | Type | Descrption | - | :--: | ---------- | - | 1 | Marketing | - | 3 | Rules | - | 4 | Bots default | - | 6 | New account creation follow-up | - | 7 | Device alert | - | 8 | App default | - | 11 | Account issues | - | 13 | OAuth client | - | 16 | Device firmware update | - | 17 | SMS chat | - | 18 | Location | - | 19 | Bot error | - | 20 | Badge | - | 22 | Bot report | - | 23 | Message | + This operation is not atomic. It will try to execute all commands in the same order, as they are provided. + If some command fails, it will execute the next one. The result code is returned for each command. tags: - - User Communications - security: - - userApiKey: [] - parameters: - - name: userId - in: query - description: Send a notification to this user by an administrator - schema: - type: integer + - Device Measurements + security: + - userApiKey: [] + parameters: - name: locationId in: query - description: Send a notification to users on this location - schema: - type: integer - - name: organizationId - in: query - description: Use templates of specific organization + description: Devices location ID + required: true schema: type: integer requestBody: content: application/json: example: - brand: care - userCategories: - - 1 - - 2 - users: - - 123 - - 234 - - 345 - language: en - pushMessage: - type: 8 - badgeType: 1 - template: directoryName/PushTemplateName.vm - sound: sound.wav - content: Push notification text - smsFallback: true - smsContent: SMS fallback text - title: Title - subtitle: Subtitle - category: Category Name - model: - key0: value0 - key1: value1 - key2: value2 - info: - field0: info0 - field1: info1 - emailMessage: - subject: Subject - html: true - template: directoryName/EmailTemplateName.vm - content: Email message text - model: - key0: value0 - key1: value1 - key2: value2 - attachments: - - name: imageName.jpg - content: /9j/4AAQSkZJRgABAgEAAAAAAAD/4 - contentType: image/jpeg - contentId: inlineImageId - - name: fileName.jpg - deviceFileId: 123456 - contentId: inlineFileId - smsMessage: - categories: - - 0 - - 1 - template: directoryName/SmsTemplateName.vm - content: Sms message text - individual: true - model: - key0: value0 - key1: value1 - key2: value2 - deviceMessage: - deviceId: optional device ID - title: string - text: string - from: string - duration: 0 - icon: string - muted: true - imageUrl: string - image: base64 encoded image + devices: + - deviceId: ABC123 + commandType: 0 + commandTimeout: 15000 + params: + - name: outletStatus + index: '0' + value: '1' + - name: ppc.lowPowerMode + value: '0' + comment: Why this command has been sent schema: type: object properties: - brand: - type: string - description: Notification template brand - userCategories: - type: array - description: Notify location uses of these categories - items: - type: integer - users: + devices: type: array - description: Notify these uses items: - type: integer - language: - type: string - description: Message language - pushMessage: - type: object - description: Push notification - properties: - type: - type: integer - description: Notification type - badgeType: - type: integer - description: Badge type - template: - type: string - description: Template to generate notification text - sound: - type: string - content: - type: string - description: Notification text - smsFallback: - type: boolean - description: Send SMS, if the user does not have valid notification tokens - smsContent: - type: string - description: Fallback SMS text - title: - type: string - subtitle: - type: string - category: - type: string - model: - type: object - additionalProperties: - type: string - description: Notification template parameters key/value string map - info: - type: object - additionalProperties: - type: string - description: Additional push notification parameters key/value string map - emailMessage: - type: object - description: Email - properties: - subject: - type: string - description: Email subject - html: - type: boolean - description: Send email in HTTP format - template: - type: string - description: Template to generate email text - content: - type: string - description: Email text - model: - type: object - additionalProperties: + type: object + properties: + deviceId: type: string - description: Notification template parameters key/value string map - attachments: - type: array - description: Email attachments - items: - type: object - properties: - name: - type: string - description: Attachment name - content: - type: string - description: Attachment Base64 encoded content - contentType: - type: string - description: Attachment content type - contentId: - type: string - description: Inline content ID - deviceFileId: - type: integer - description: Use this device file thumbnail as the content - required: - - name - smsMessage: - type: object - properties: - template: - type: string - description: Template to generate message text - content: - type: string - description: Message text - individual: - type: boolean - description: If this message to be sent to individual users or to a chat group - model: - type: object - additionalProperties: + description: Device ID + commandType: + type: integer + description: Optional command type, default is 0 + commandTimeout: + type: integer + description: Optional command timeout in milliseconds from the creation time + comment: type: string - description: Notification template parameters key/value string map - deviceMessage: - type: object - description: Message to be delivered to an IoT device - properties: - deviceId: - type: string - title: - type: string - text: - type: string - from: - type: string - duration: - type: integer - icon: - type: string - muted: - type: boolean - imageUrl: - type: string - image: - type: string + description: Comment describes, why this command was made + params: + type: array + items: + type: object + properties: + name: + type: string + description: Configured parameter name + index: + type: string + description: Device part index is needed, if the device interprets or expects an index value + value: + type: string + description: New parameter value or value for a specific command or null to request it from the device by the get command + unit: + type: string + description: Unit can be used, if the app needs to use non-system unit for this parameter + required: + - name + required: + - deviceId responses: '200': - description: OK + description: Commands execution results content: application/json: schema: @@ -9157,77 +7993,311 @@ paths: properties: resultCode: type: integer + commands: + type: array + items: + type: object + properties: + id: + type: integer + deviceId: + type: string + resultCode: + type: integer + resultCodeMessage: + type: string example: resultCode: 0 + commands: + - id: 123 + deviceId: ABC123 + resultCode: 0 + resultCodeMessage: Error message + + /cloud/json/devices/{deviceId}/parametersByDate/{startDate}: get: - summary: Get Notifications - operationId: Get Notifications - description: |- - Delivery types: + summary: Get History of Measurements + operationId: Get History of Measurements + tags: + - Device Measurements + security: + - userApiKey: [] + parameters: + - name: deviceId + in: path + description: Device ID for which to get a history of measurements + required: true + schema: + type: string + - name: locationId + in: query + description: Location ID + required: true + schema: + type: integer + - name: startDate + in: path + description: Start date to begin receiving measurements, for example 2014-08-01T12:00:00-08:00 + required: true + schema: + type: string + - name: endDate + in: query + description: >- + End date to stop receiving measurements, for example 2014-08-01T13:00:00-08:00. + Default is the current date. + schema: + type: string + - name: paramName + in: query + description: Only obtain measurements for given parameter names. Multiple values can be passed. + schema: + type: string + - name: index + in: query + description: Only obtain measurements for parameters with this index value + schema: + type: string + - name: rangeOnly + in: query + description: Return parameters stored exactly between start and end dates + schema: + type: boolean + - name: reduceNoise + in: query + description: Return tiny parameter values less than defined threshold as zero + schema: + type: boolean + - name: interval + in: query + description: Aggregate the readings by this interval, in minutes + schema: + type: integer + - name: aggregation + in: query + description: |- + Interval aggregation algorithm: +
0 = last value before the interval point - default +
1 = minimum value +
2 = maximum value +
3 = median value +
4 = time distributed average value +
5 = average value + schema: + type: integer + enum: [0,1,2,3,4,5] + - name: sortOrder + in: query + description: Order result by timestamp
asc = ascending
desc = descending + schema: + type: string + enum: [asc,desc] + responses: + '200': + description: Measurements history + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + readings: + type: array + items: + type: object + properties: + deviceId: + type: string + timeStamp: + type: string + timeStampMs: + type: integer + params: + type: array + items: + type: object + properties: + name: + type: string + index: + type: string + value: + type: string + required: + - name + required: + - deviceId + - timeStamp + - timeStampMs + - params + example: + resultCode: 0 + readings: + - deviceId: MON9648 + timeStamp: '2014-12-21T00:58:49-04:00' + timeStampMs: 1419137929000 + params: + - name: power + value: '865' + - name: energy + value: '0.003' + - deviceId: MON9648 + timeStamp: '2014-12-21T00:58:49-04:00' + timeStampMs: 1419137929000 + params: + - name: energy + value: '0.004' - | Delivery | Description | - | :------: | ----------- | - | 1 | Push notification | - | 2 | Email | - | 3 | Outgoing SMS | - | 4 | Incoming SMS | - Source types: + /cloud/json/devices/{deviceId}/parametersByCount/{rowCount}: + get: + summary: Get the Last N Measurements + operationId: Get the Last N Measurements + description: >- + The first timestamp reading will contain all measured parameters and their values. + All other timestamp readings will only contain the parameters that changed in value. + tags: + - Device Measurements + security: + - userApiKey: [] + parameters: + - name: deviceId + in: path + description: Device ID for which to obtain measurements + required: true + schema: + type: string + - name: locationId + in: query + description: Location ID + required: true + schema: + type: integer + - name: rowCount + in: path + description: Maximum number of measurements to obtain + required: true + schema: + type: integer + - name: startDate + in: query + description: Start date to begin receiving measurements, for example 2014-08-01T12:00:00-08:00 + required: true + schema: + type: string + - name: endDate + in: query + description: >- + End date to stop receiving measurements, for example 2014-08-01T13:00:00-08:00. + Default is the current date. + schema: + type: string + - name: paramName + in: query + description: Only obtain measurements for given parameter names. Multiple values can be passed. + schema: + type: string + - name: index + in: query + description: Only obtain measurements for parameters with this index value. + schema: + type: string + - name: reduceNoise + in: query + description: Return tiny parameter values less than defined threshold as zero + schema: + type: boolean + responses: + '200': + description: Measurements history + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + readings: + type: array + items: + type: object + properties: + deviceId: + type: string + timeStamp: + type: string + timeStampMs: + type: integer + params: + type: array + items: + type: object + properties: + name: + type: string + index: + type: string + value: + type: string + required: + - name + example: + resultCode: 0 + readings: + - deviceId: ea5101a8005f-10031-470 + timeStamp: '2014-08-01T13:00:00-08:00' + timeStampMs: 1419137929000 + params: + - name: status + value: Accepting new devices + - name: progress + value: '100' + - | Source | Description | - | :----: | ----------- | - | 0 | External API call | - | 1 | Rule | - | 2 | Bot | - | 4 | Device firmware update | - | 5 | Internal system logic like account issue | - | 6 | Cloud business logic | - | 7 | External incoming message | + /cloud/json/alerts: + get: + summary: Get History of Device Alerts + operationId: Get History of Alerts + description: '' tags: - - User Communications + - Device Measurements security: - userApiKey: [] parameters: - - name: userId - in: query - description: Get notifications for this user by an administrator - schema: - type: integer - - name: startDate - in: query - description: Start date to select notifications - required: true - schema: - type: string - - name: endDate + - name: deviceId in: query - description: End date to select notifications. Default is the current date. + description: Device ID for which to get a history of alerts schema: type: string - name: locationId in: query - description: Get notifications related to this location + description: Location ID + required: true schema: type: integer - - name: sourceType + - name: alertType in: query - description: Filter by source type + description: Retrieve only alerts of this type schema: - type: integer - - name: deliveryType + type: string + - name: startDate in: query - description: Filter by delivery type + description: Start date to begin receiving alerts, for example 2014-08-01T12:00:00-08:00 + required: true schema: - type: integer - - name: notificationType + type: string + - name: endDate in: query - description: Filter by notification type + description: >- + End date to stop receiving alerts, for example 2014-08-01T13:00:00-08:00. + Default is the current date. schema: - type: integer + type: string responses: '200': - description: Notifications history + description: Device alerts history content: application/json: schema: @@ -9235,134 +8305,220 @@ paths: properties: resultCode: type: integer - notifications: + alerts: type: array items: type: object properties: - sendDate: + deviceId: type: string - sendDateMs: - type: integer - deliveryType: - type: integer - notificationType: - type: integer - locationId: - type: integer - brand: + alertType: type: string - templateName: + receivingDate: type: string - language: + receivingDateMs: + type: integer + params: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + required: + - name + - value + required: + - deviceId + - alertType + - receivingDate + - receivingDateMs + example: + resultCode: 0 + alerts: + - deviceId: MON9648 + alertType: motion + receivingDate: '2014-12-21T00:58:49-04:00' + receivingDateMs: 1419137929000 + params: + - name: fileRef + value: '865' + - name: count + value: '10' + + + /cloud/json/dataRequests: + post: + summary: Submit Data Request + operationId: Submit Data Request + description: |- + Selecting large amount of data from the database can take significant time. + To avoid this long waiting period a user can submit requests for all data to the server asynchronously. + When the requests will be completed, the user will be notified by email. + + Selected data will be uploaded to S3 in CSV format (compressed) and stored for one day. + Links to download the data files will be sent by email by the user's request. + Otherwise, they can be received by calling the get data API. + + Following data types are available for requesting: + + | Type | Details | + | :--: | :------ | + | 1 | Device parameters history | + | 2 | Device activities history | + | 3 | Organization locations | + | 4 | Location modes history | + | 5 | Location narratives | + | 6 | Organization devices | + | 7 | Data streams | + | 8 | Energy usage | + | 9 | Device alerts history | + | 10 | Location Time States | + tags: + - Device Measurements + security: + - userApiKey: [] + parameters: + - name: locationId + in: query + description: Request information from specific location + schema: + type: integer + requestBody: + content: + application/json: + example: + brand: care + byEmail: true + dataRequests: + - type: 1 + key: Front door history + deviceId: ABC123 + startTime: 1446537883000 + endTime: 1456537883000 + paramNames: + - doorStatus + index: '0' + ordered: 1 + compression: 1 + schema: + type: object + properties: + brand: + type: string + description: Notification brand + byEmail: + type: boolean + description: Notify the user by email, when the request completed. + dataRequests: + type: array + description: Data requests + items: + type: object + properties: + type: + type: integer + enum: [1,2,3,4,5,6,7,8,9,10] + description: Data type + key: + type: string + description: Optional request key + deviceId: + type: string + description: Device ID required for data types 1,2,8,9 + startTime: + type: integer + description: Period start time in milliseconds required for data types 1,2,5,7,8,9,10 + endTime: + type: integer + description: Period end time in milliseconds required for data types 1,2,5,7,8,9,10 + paramNames: + type: array + description: Device parameter names optional for data type 1 + items: type: string - sound: + index: + type: string + description: Device part index optional for data type 1 + organizationId: + type: integer + description: Organization ID required for data types 3,6,10 + searchBy: + type: string + description: Search string optional for data type 3. Use '*' for wildcard. + locationTags: + type: array + description: Location search tags optional for data type 3 + items: type: string - badge: - type: integer - sentCount: - type: integer - sourceType: - type: integer - sourceId: + deviceTags: + type: array + description: Device search tags optional for data type 3 + items: + type: string + deviceTypes: + type: array + description: Device search types optional for data types 3,6 + items: type: integer - messageText: + names: + type: array + description: Location state names required for the data type 10 + items: type: string + aggregation: + type: integer + description: Data aggregation by:
0 = None
1 = Hours
2 = Days
3 = Months
4 = 7-day weeks
5 = 5-day weeks
required for data type 8 + ordered: + type: integer + description: Order data by timestamp
1 = ASC
-1 = DESC
optional for data types 1,2,4,5,9 + compression: + type: integer + description: Data compression
0 = LZ4, default
1 = ZIP
2 = none + required: + - type + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer example: resultCode: 0 - notifications: - - sendDate: '2018-06-12T12:24:48Z' - sendDateMs: 1419137929000 - deliveryType: 1 - notificationType: 7 - locationId: 123 - brand: care - templateName: alert/motion_detected.vm - language: en - sound: default - badge: 1 - sentCount: 3 - sourceType: 6 - sourceId: 1234 - messageText: Motion detected on your camera - - /cloud/json/ticket: - post: - summary: Post Support Ticket - operationId: Post Support Ticket - description: |- - Create a support ticket. - - | Type | Details | - | :--: | ------- | - | 1 | problem | - | 2 | incident | - | 3 | question | - | 4 | task | - - Ticket priority is from 1 (low) to 4 (urgent). - - The request is executed asynchronously. The user will be notified about created ticket. + get: + summary: Get Requested Data + operationId: Get Requested Data + description: Completed data requests can be retrieved by calling this API. tags: - - User Communications + - Device Measurements security: - userApiKey: [] parameters: - - name: userId + - name: locationId in: query - description: Request support for this user by an administrator + description: Location ID schema: type: integer - - name: locationId + - name: organizationId in: query - description: Request support for this location + description: Organization ID schema: type: integer - requestBody: - content: - application/json: - example: - brand: family - lang: en - ticket: - type: 1 - priority: 3 - subject: Nice feature - comment: May I ask you to add a new feature to the app? - customFields: - - id: 123 - value: abc - schema: - type: object - properties: - brand: - type: string - lang: - type: string - ticket: - type: object - properties: - type: - type: integer - priority: - type: integer - subject: - type: string - comment: - type: string - customFields: - type: array - items: - type: object - properties: - id: - type: integer - value: - type: string + - name: requestKey + in: query + description: Filter by data request key + schema: + type: string responses: '200': - description: OK + description: Data requests history content: application/json: schema: @@ -9370,254 +8526,400 @@ paths: properties: resultCode: type: integer + results: + type: array + items: + type: object + properties: + type: + type: integer + description: Data request type + key: + type: string + description: Request key + url: + type: string + description: Data download URL + completionDate: + type: string + description: Request completion date + completionDateMs: + type: integer + expiryDate: + type: string + description: Data URL expiry date + expiryDateMs: + type: integer + deviceId: + type: string + description: Requested data device ID + startDate: + type: string + description: Requested data start date + startDateMs: + type: integer + endDate: + type: string + description: Requested data end date + endDateMs: + type: integer example: resultCode: 0 + results: + - type: 1 + key: Front door history + url: >- + https://s3.amazonaws.com/bucket/fileId?X-Amz-Algorithm=AWS4-HMAC-SHA256 + completionDate: '2019-04-08T12:13:14Z' + completionDateMs: 1456537883000 + expiryDate: '2019-04-09T12:13:14Z' + expiryDateMs: 1456557883000 + deviceId: ABC123 + startDate: '2010-01-01T00:00:00Z' + startDateMs: 1446537883000 + endDate: '2020-01-01T00:00:00Z' + endDateMs: 1646537883000 - /cloud/json/feedback: - post: - summary: Post Crowd Feedback - operationId: Post Crowd Feedback - description: |- - Crowd feedback is first delivered to a support email for moderation. - If the feedback is unique, then the support staff will make it public for other users to vote on. - - The API returns the created feedback record ID and if a ticket has been created in a support cloud, then the ticket ID and the brand name. + /cloud/json/units: + get: + summary: Get Units of Measurement + operationId: Get Units of Measurement tags: - - User Communications - security: - - userApiKey: [] - parameters: - - name: userId - in: query - description: Send a feedback for this user by an administrator - schema: - type: integer - - name: brand - in: query - description: Application brand - schema: - type: string - requestBody: - content: - application/json: - example: - feedback: - appName: Care - appVersion: 2.0.1 - type: 1 - subject: Nice feature - email: john@mail.com - deviceId: ABC123 - deviceModel: iPhone - deviceOs: 7.0.4 - productId: 123 - productCategory: 2200 - viewer: Android Samsung S3 - description: It would be best if the app will be able to .. - schema: - type: object - properties: - feedback: - type: object - properties: - appName: - type: string - description: Unique name / identifier of the app or product, selected by the developer - appVersion: - type: string - description: Version of the app that generated this request - type: - type: integer - enum: [1,2] - description: >- - 1 - New feature request -
2 - Problem report - subject: - type: string - description: Subject line describing the feature or issue - email: - type: string - description: Email address of the user generating this request, not shown publicly. - deviceId: - type: string - description: Problem device ID - deviceModel: - type: string - description: Model of the device that generated the request (i.e. iPhone5,1) - deviceOs: - type: string - description: Operating system on the device that generated the request (i.e. iOS 8.1.2) - productId: - type: integer - description: Product ID, present if the user is giving feedback on a specific type of product. - productCategory: - type: integer - description: Category of the product, present if the user is giving feedback on a specific type of product. - viewer: - type: string - description: Viewer description - description: - type: string - description: |- - "I want the product to also do ..." + - Device Measurements responses: '200': - description: OK + description: Device Parameter Units content: application/json: schema: type: object - properties: - resultCode: - type: integer - feedbackId: - type: integer - brand: - type: string - ticketId: + properties: + resultCode: type: integer + units: + type: array + items: + type: object + properties: + unit: + type: string + description: + type: string + required: + - unit + - description example: resultCode: 0 - feedbackId: 123 - brand: care - ticketId: 12345 + units: + - unit: A + description: Current Ampere + - unit: A/A + description: Ratio of amperages, A/A + - unit: A/m + description: Magnetic field strength (A/m) + - unit: A^2 + description: Amps squared (A?) + - unit: A^2h + description: Ampere-squared hour (A^2h) + - unit: A^2s + description: Ampere-squared second (A^2s) + - unit: Ah + description: Ampere-hours + - unit: As + description: Amp seconds + - unit: B + description: Sound pressure level, Bel. Combine with multiplier prefix 'd' to form decibels of Sound Pressure Level 'dB' + - unit: Bm + description: Signal Strength, Bel-mW, normalized to 1mW. To form 'dBm', combine 'Bm' with multiplier 'd'. + - unit: Bq + description: Radioactivity (l/s) + - unit: C + description: Electric charge (AS) + - unit: F + description: Electric capacitance (C/V) + - unit: Gy + description: Absorbed dose (J/kg) + - unit: H + description: Electric inductance (Wb/A) + - unit: Hz + description: Frequency hertz (1/s) + - unit: Hz/Hz + description: Rate of change of frequency + - unit: Hz/s + description: Rate of change of frequency + - unit: J + description: Energy joule (N m) + - unit: J/K + description: Heat capacity + - unit: J/kg + description: Joules per kilogram + - unit: J/m^2 + description: Solar radiation + - unit: K + description: Absolute Temperature + - unit: L + description: Litre + - unit: L/L + description: Concentration, The ratio of the volume of a solute divided by the volume of the solution., L/L + - unit: L/h + description: Litres per hour + - unit: L/s + description: Volumetric flow rate, Volumetric flow rate, L/s + - unit: Lm + description: Luminous flux (cd sr) + - unit: 'N' + description: Force newton (kg m/s^2) + - unit: Pa + description: Pressure (N/m?) + - unit: PaA + description: Pressure, Pascal, absolute pressure, PaA + - unit: PaG + description: Pressure, Pascal, gauge pressure, PaG + - unit: Q + description: Quantity power + - unit: Qh + description: Quantity energy + - unit: Siemens + description: Electric conductance (A/V) + - unit: Sv + description: Dose equivalent (J/kg) + - unit: T + description: Magnetic flux density (Wb/m^2) + - unit: V + description: Electric potential (W/A) + - unit: V/Hz + description: Magnetic flux + - unit: V/V + description: Voltage, Ratio of voltages (e.g. mV/V), V/V + - unit: VA + description: Apparant power (VA) + - unit: VAh + description: Apparant energy + - unit: VAh/rev + description: Kh-Vah, apparent energy metering constant, VAh/rev + - unit: VAr + description: Reactive power (Volt Ampere reactive (VI Sin Theta)) + - unit: VArh + description: Reactive energy + - unit: VArh/rev + description: Kh-VArh, reactive energy metering constant, VArh/rev + - unit: V^2 + description: Volts squared (W^2/A?^2 + - unit: V^2h + description: Volt-squared hour (V^2h) + - unit: Vs + description: Volt seconds (Ws/A) + - unit: W + description: Real power (I^2R) + - unit: W/W + description: Signal Strength, Ratio of power, W/W + - unit: W/m K + description: Thermal conductivity + - unit: W/s + description: Watts per second + - unit: Wb + description: Magnetic flux (V s) + - unit: Wh + description: Real energy + - unit: Wh/m^3 + description: Energy per volume (Wh/m^3) + - unit: Wh/rev + description: Kh-Wh, active energy metering constant, Wh/rev + - unit: boolean + description: Boolean (0 or 1) + - unit: btu + description: British Thermal Units + - unit: btu/h + description: British Thermal Units per hour + - unit: cd + description: Luminous intensity + - unit: char + description: Number of characters + - unit: char/s + description: Data rate + - unit: count + description: Counter Value (0, 1, 2, 3, 4, ...) + - unit: deg + description: Plane angle + - unit: degrees C + description: Relative Temperature in Celsius + - unit: degrees F + description: Relative Temperature in Fahrenheit + - unit: degrees Theta + description: Phase angle + - unit: ft^3 + description: Volume, cubic feet + - unit: ft^3/h + description: Cubic feet per hour + - unit: g + description: Mass + - unit: g/kg + description: Ratio of mass + - unit: gM2 + description: Turbine inertia, gram*meter2 (Combine with multiplier prefix 'k' to form kg*m2.) + - unit: gPerG + description: Concentration, The ratio of the mass of a solute divided by the mass of the solution., g/g + - unit: gif + description: GIF image + - unit: hour + description: Hour + - unit: imperialGal + description: Volume, imperial gallons, ImperialGal + - unit: imperialGalPerH + description: Volumetric flow rate, Imperial gallons per hour, ImperialGal/h + - unit: int + description: Generic Int + - unit: jpg + description: JPEG Image + - unit: json + description: JSON object + - unit: kat + description: Catalytic activity, katal = mol / s, kat + - unit: kg/m^3 + description: Density + - unit: kgM + description: Moment of mass, kilogram meter (kg*m), M + - unit: lx + description: Illuminance lux (lm/m^2) + - unit: m + description: Length + - unit: m/m + description: Length, Ratio of length, m/m + - unit: m/m^3 + description: Fuel efficiency (m/m^3) + - unit: m/s + description: Velocity + - unit: m/s^2 + description: Acceleration + - unit: m^2 + description: Area + - unit: m^2/s + description: Viscosity + - unit: m^3 + description: Volume + - unit: m^3/h + description: Volumetric flow rate (m^3/s) + - unit: m^3/s + description: Volumetric flow rate (m^3/s) + - unit: minute + description: Minute + - unit: mol + description: Amount of Substance + - unit: mol/kg + description: Concentration, Molality, the amount of solute in moles and the amount of solvent in kilograms., mol/kg + - unit: mol/m^3 + description: >- + Concentration, The amount of substance concentration, (c), + the amount of solvent in moles divided by the volume of solution in m^3, mol/m^3 + - unit: mol/mol + description: >- + Concentration, Molar fraction, the ratio of the molar + amount of a solute divided by the molar amount of the solution.,mol/mol + - unit: money + description: Money + - unit: ohm + description: Electric resistance (VA) + - unit: pf + description: Power factor (dimensionless, Cos Phi) + - unit: ppm + description: Concentration + - unit: psiA + description: Pressure, Pounds per square inch, absolute, psiA + - unit: psiG + description: Pressure, Pounds per square inch, gauge, psiG + - unit: q45 + description: Quantity power, Q measured at 45º, Q45 + - unit: q45h + description: Quantity energy, Q measured at 45º, Q45h + - unit: q60 + description: Quantity power, Q measured at 60º, Q60 + - unit: q60h + description: Quantity energy, Qh measured at 60º, Q60h + - unit: rad + description: Plane angle + - unit: rad/s + description: Angular velocity + - unit: relativeHumidity + description: >- + Relative humidity, the ratio of partial pressure of water + vapor in the air-water mixture to the saturated vapor + pressure of water at those conditions + - unit: rev + description: Amount of rotation, Revolutions, rev + - unit: rev/s + description: Rotational Speed + - unit: rho + description: Resistivity (rho) (Ohm) + - unit: s + description: Time (seconds) + - unit: s/s + description: >- + Time, Ratio of time (can be combined with an multiplier + prefix to show rates such as a clock drift rate, e.g. 's/s'), s/s + - unit: specificHumidity + description: >- + Specific humidity is expressed as a ratio of mass of water + vapor per unit mass of dry air + - unit: sr + description: Solid angle + - unit: string + description: Generic text string + - unit: therm + description: Energy, Therm, therm + - unit: timestamp + description: Timestamp (ISO 8601) + - unit: usGal + description: Volume, US gallons, Gal + - unit: usGal/h + description: Volumetric flow rate, US gallons per hour, USGal/h + - unit: version + description: Generic version number + - unit: zipCode + description: Zip / Territory / Postal Code - /cloud/json/feedback/{appName}/{type}: + /cloud/json/notificationSubscriptions: get: - summary: Get Crowd Feedback by Searching - operationId: Get Crowd Feedback by Searching + summary: Get Notification Subscriptions + operationId: Get Notification Subscriptions tags: - User Communications - security: - - userApiKey: [] - parameters: - - name: appName - in: path - description: Unique name / identifier of the app or product, selected by the developer - required: true - schema: - type: string - - name: type - in: path - description: 1 - New feature request
2 - Problem report - required: true - schema: - type: integer - enum: [1,2] - - name: startPos - in: query - description: Index of the first record to be returned. - schema: - type: integer - - name: length - in: query - description: Number of records to return. - required: true - schema: - type: integer - - name: productId - in: query - description: Filter the response by product ID. You may include multiple of these parameters to filter by multiple product IDs. - schema: - type: integer - - name: productCategory - in: query - description: Filter the response by product category. You may include multiple of these parameters to filter by multiple product categories. - schema: - type: integer - - name: disabled - in: query - description: Return not enabled feedbacks as well. - schema: - type: boolean - responses: - '200': - description: Feedbacks - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - feedbacks: - type: array - items: - type: object - properties: - id: - type: integer - appName: - type: string - appVersion: - type: string - type: - type: integer - subject: - type: string - email: - type: string - deviceId: - type: string - deviceModel: - type: string - deviceOs: - type: string - productId: - type: integer - productCategory: - type: integer - viewer: - type: string - description: - type: string - votingCount: - type: integer - rank: - type: integer - enabled: - type: boolean - example: - resultCode: 0 - feedbacks: - - id: 123 - appName: Care - appVersion: 2.0.1 - type: 1 - subject: Nice feature - email: john@mail.com - deviceId: ABC123 - deviceModel: iPhone - deviceOs: 7.0.4 - productId: 123 - productCategory: 2200 - viewer: Android Samsung S3 - description: It would be best if the app will be able to .. - votingCount: 10 - rank: 1 - enabled: true + description: |- + A user may subscribe or unsubscribe from certain types of push and email notifications, + or set boundaries on how many notifications their account can receive within a specified amount of time. + The Care Daily AI Platform supports following notification types: - /cloud/json/feedback/{feedbackId}: - get: - summary: Get Specific Crowd Feedback - operationId: Get Specific Crowd Feedback - tags: - - User Communications + | Type | Description | Transport | Configurable | Location | + | :--: | ----------- | :-------: | :----------: | :------: | + | 0 | Unsubscribe from all | Email Push SMS | * | | + | 1 | Marketing emails | Email | * | | + | 3 | Rules| Email Push | | | + | 4 | Bots | Email Push SMS | * | * | + | 7 | Device alerts | Email Push | * | * | + | 8 | Apps | Email Push | * | * | + | 11 | Account issues | Push | | | + | 13 | OAuth client | Email Push | * | * | + | 16 | Device firmware update | Push | | | + | 17 | SMS chat | Push SMS | | | + | 18 | Location messages | SMS | | | + | 19 | Bot errors to developers | Email | * | | + | 20 | App badge change | Push | | | + | 22 | Bot reports | Email Push SMS | * | * | + | 23 | Messages | Email Push SMS | * | * | security: - userApiKey: [] + - botApiKey: [] parameters: - - name: feedbackId - in: path - description: Specific feedback ID - required: true + - name: userId + in: query + description: User ID for bots and administrators schema: type: integer responses: '200': - description: Feedback + description: Notification Subscriptions content: application/json: schema: @@ -9625,144 +8927,135 @@ paths: properties: resultCode: type: integer - feedbacks: + subscriptions: type: array items: type: object properties: - id: - type: integer - appName: - type: string - appVersion: - type: string type: type: integer - subject: - type: string - email: - type: string - deviceId: - type: string - deviceModel: - type: string - deviceOs: + description: Notification type + name: type: string - productId: - type: integer - productCategory: + description: Notification type name + locationId: type: integer - viewer: - type: string - description: - type: string - votingCount: + description: Subscription related location ID + email: + type: boolean + description: Notifications by email enabled + push: + type: boolean + description: Push notifications enabled + sms: + type: boolean + description: Notifications by SMS enabled + emailPeriod: type: integer - rank: + description: How long to wait between emails in seconds + pushPeriod: type: integer - enabled: - type: boolean + description: How long to wait between push notifications in seconds + required: + - type + - email + - push + - sms example: resultCode: 0 - feedbacks: - - id: 123 - appName: Care - appVersion: 2.0.1 - type: 1 - subject: Nice feature - email: john@mail.com - deviceId: ABC123 - deviceModel: iPhone - deviceOs: 7.0.4 - productId: 123 - productCategory: 2200 - viewer: Android Samsung S3 - description: It would be best if the app will be able to .. - votingCount: 10 - rank: 1 - enabled: true + subscriptions: + - type: 0 + locationId: 0 + email: true + push: true + sms: false + name: All + emailPeriod: 0 + pushPeriod: 0 + - type: 6 + locationId: 0 + email: false + push: false + sms: false + name: Registration follow up + emailPeriod: 0 + pushPeriod: 0 + - type: 7 + locationId: 123 + email: true + push: true + sms: false + name: Device alerts + emailPeriod: 0 + pushPeriod: 0 + - type: 8 + locationId: 123 + email: true + push: true + sms: false + name: Analytics and external + emailPeriod: 0 + pushPeriod: 0 - /cloud/json/feedback/{feedbackId}/{rank}: + /cloud/json/notificationSubscriptions/{type}: put: - summary: Vote for Feedback - operationId: Vote for Feedback + summary: Set Notification Subscriptions + operationId: Set Notification Subscriptions + description: '' tags: - User Communications security: - userApiKey: [] + - botApiKey: [] parameters: - - name: feedbackId + - name: type in: path - description: Feedback ID to vote on + description: Type of notification, as defined by the Care Daily AI Platform during the request to Get Subscription Notifications. required: true schema: type: integer - - name: rank - in: path - description: 'Rank: 1 to cast a vote, 0 to remove a vote.' - required: true + - name: userId + in: query + description: User ID for bots and administrators schema: type: integer - responses: - '200': - description: OK - headers: {} - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/json/support: - post: - summary: Request Support - operationId: Request Support - description: If a ticket has been created in a support cloud, then the API returns the ticket ID and the brand name. - tags: - - User Communications - parameters: - - name: brand + - name: locationId in: query - description: Brand of the support request templates + description: Location ID schema: - type: string - requestBody: - content: - application/json: - example: - firstName: John - lastName: Smith - email: john.smith@example.com - subject: Subject text - text: Comments or questions - subscribe: This user wants to subscribe to XYZ - schema: - type: object - properties: - firstName: - type: string - description: First name (what do your friends call you?) - lastName: - type: string - description: Last name - email: - type: string - description: Reply email address - subject: - type: string - description: Subject line, short description of the issue - text: - type: string - description: The actual comments from the user - subscribe: - type: string - description: Text describing whether or not the user wants to subscribe to newsletters, etc. It's a manual process on the backend. + type: integer + - name: email + in: query + description: >- + true - Email notifications enabled +
false - No email notifications + schema: + type: boolean + - name: push + in: query + description: >- + true - Push notifications enabled +
false - No push notifications + schema: + type: boolean + - name: sms + in: query + description: >- + true - SMS notifications enabled +
false - No SMS notifications + schema: + type: boolean + - name: emailPeriod + in: query + description: Minimum number of seconds between email notifications + schema: + type: integer + - name: pushPeriod + in: query + description: Minimum number of seconds between push notifications + schema: + type: integer responses: '200': description: OK @@ -9773,346 +9066,72 @@ paths: properties: resultCode: type: integer - brand: - type: string - ticketId: - type: integer example: resultCode: 0 - brand: care - ticketId: 12345 - /cloud/json/messageTopics: - get: - summary: Get Message Topics - operationId: Get Message Topics + /cloud/json/notificationToken/{appName}/{token}: + put: + summary: Register App for Push Notifications + operationId: Register App for Push Notifications tags: - User Communications security: - userApiKey: [] - - botApiKey: [] parameters: - - name: appId + - name: appName + in: path + description: Unique App Name to register for push notifications + required: true + schema: + type: string + - name: token + in: path + description: The iOS notification token or the Android device registration ID + required: true + schema: + type: string + - name: badge in: query - description: Bot ID + description: >- + true - This app supports badge icons +
false - This app does not support badge icons, default schema: - type: integer - - name: lang + type: boolean + - name: brand in: query - description: Preferred content language + description: If set, the app will not receive notifications addressed to different brands schema: type: string responses: '200': - description: Message Topics + description: OK content: application/json: schema: type: object properties: resultCode: - type: integer - topics: - type: array - items: - type: object - properties: - topicId: - type: string - name: - type: string - bots: - type: array - items: - type: object - properties: - appId: - type: integer - bundle: - type: string - name: - type: string - author: - type: string - category: - type: string - type: - type: integer - core: - type: integer - required: - - appId - - bundle - - name - - author - - category - - type - - core - required: - - topicId - - name - - bots - example: - resultCode: 0 - topics: - - topicId: general - name: General - bots: - - appId: 2345 - bundle: com.peoplepowerco.engage - name: My Engage Bot - author: Your Company - category: S,W - type: 0 - core: -1 - - topicId: engage - name: Engage - bots: - - appId: 2345 - bundle: com.peoplepowerco.engage - name: My Engage Bot - author: Your Company - category: S,W - type: 0 - core: -1 - - - /cloud/json/messages: - post: - summary: Create Messages - operationId: Create Messages - description: |- - Message APIs allow to create, schedule, and retrieve messages from AI bots to location users. - - ### Message Statuses - - | Status | Description | - |:------:|------------------------| - | 0 | Initial, storage only | - | 1 | Ready for scheduling | - | 2 | Scheduled for delivery | - | 3 | Delivered | - | 4 | Deleted | + type: integer + example: + resultCode: 0 - ### Scheduling Types - - | Type | Description | - |:----:|-------------| - | 0 | One-time | - | 1 | Recurring | - - One-time messages will be delivered to users only once, when the status is set to `2` or `3`. - - Notifications from recurring messages can be delivered multiple times according to the notification schedule until the maximum delivery date, when the message has the status `2`. - - Delivered messages will have status `3`. - - ### Delivery Types - - A message content can be delivered to users over different notification channels. - - | Type | Description | - |:----:|-------------| - | 0 | In-App | - | 1 | Push | - | 2 | Email | - | 3 | SMS | - - A message content with the delivery type `0` "In-App" will be returned from the get message API. - It is always required, when a message is created. - - ### Text Content Types - - | Type | Description | Delivery Types | - |:----:|----------------| -------------- | - | 0 | Text (default) | All | - | 1 | HTML | Email only | - | 2 | Markdown | In-App only | - - AI bots and users can create new messages using this API. - User messages always have status delivered. + /cloud/json/notificationToken/{token}: + delete: + summary: Unregister App for Push Notifications + operationId: Unregister App for Push Notifications tags: - User Communications security: - userApiKey: [] - - botApiKey: [] parameters: - - name: locationId - in: query - description: Location ID, when created by a user + - name: token + in: path + description: The iOS notification token or the Android device registration ID + required: true schema: - type: integer - requestBody: - content: - application/json: - example: - messages: - - status: 1 - originalMessageId: 111 - topicId: general - scheduleType: 0 - contentKey: Short content description - contents: - - deliveryType: 0 - contentType: 2 - text: - en: In-App message text - es: ... - - deliveryType: 1 - contentType: 0 - text: - en: Push notification - es: ... - title: Title - subtitle: Subtitle - category: 21.0.1 - sound: sound.wav - - deliveryType: 2 - contentType: 1 - text: - en: Email message text - es: ... - subject: - en: Email subject - es: ... - attachments: - - name: imageName.jpg - content: /9j/4AAQSkZJRgABAgEAAAAAAAD/4 - contentType: image/jpeg - contentId: inlineImageId - - deliveryType: 3 - contentType: 0 - text: - en: SMS text - es: ... - questionId: 987 - mediaUrl: https://s3.amazon.com/images/picture.png - mediaContentType: image/png - maxDeliveryDate: '2024-01-01T00:00:00Z' - deliveryDayTime: 36000 - timeToLive: 3600 - schedule: 0 0 10 ? * SUN - recipients: - - categories: - - 1 - - 2 - roles: - - 1 - - 2 - locationAccess: 10 - - userId: 678 - schema: - type: object - properties: - messages: - type: array - items: - type: object - properties: - status: - type: integer - description: Message status - originalMessageId: - type: integer - description: Top message ID in the messages thread - topicId: - type: string - description: Messages topic ID - scheduleType: - type: integer - description: Scheduling type - contentKey: - type: string - description: Descriptive text used to classify priority of the message, e.g. Fall Event or Dog Walking - contents: - type: array - description: An array of objects with localized message texts by delivery types - items: - type: object - properties: - deliveryType: - type: integer - description: Delivery type - contentType: - type: integer - description: Message text content type - text: - type: object - additionalProperties: - type: string - description: Multilingual message text string map, where the keys are language names - title: - type: string - subtitle: - type: string - category: - type: string - sound: - type: string - subject: - type: object - additionalProperties: - type: string - description: Multilingual subject string map, where the keys are language names - attachments: - type: array - description: Email attachments - items: - type: object - properties: - name: - type: string - content: - type: string - contentType: - type: string - contentId: - type: string - required: - - deliveryType - - contentType - - text - questionId: - type: integer - description: ID of a question associated with this message - mediaUrl: - type: string - description: URL of media object - mediaContentType: - type: string - description: Media object content type, e.g. image/png - maxDeliveryDate: - type: string - description: Maximum absolute time by which the message has to be delivered - deliveryDayTime: - type: integer - description: Time of the day in seconds at which the message should be delivered - timeToLive: - type: integer - description: Time in seconds from the delivery date to count the message as active for replies by SMS - schedule: - type: string - description: Cron expression for recurring delivery of notifications - recipients: - type: array - description: An array of citeria to select notification recipients - items: - type: object - properties: - categories: - type: array - items: - type: integer - roles: - type: array - items: - type: integer - locationAccess: - type: integer - userId: - type: integer + type: string responses: '200': description: OK @@ -10123,60 +9142,280 @@ paths: properties: resultCode: type: integer - messages: - type: array - items: - type: object - properties: - messageId: - type: integer example: resultCode: 0 - messages: - - messageId: 123 - put: - summary: Update Messages - operationId: Update Messages - description: AI bots can update message statuses and schedule delivery time. + + /cloud/json/notifications: + post: + summary: Send a Notification + operationId: Send a Notification + description: |- + Sends an arbitrary push notification or email to the user. + If you're sending an email, you may include a subject and specify whether the email is in HTML format or plain text. + Push notification messages are limited by the standard push notification payload size. + + This API allows to include inline graphics as an attachment. + + Attached content can be set directly. In this case all attachment fields are mandatory. The content field contains the Base64 encoded binary image content. + + Or a device file thumbnail can be used as the content. In this case all other fields are optional. + + The generated by the app email content or the template should include correct references to inline graphics content ID's with "cid:" prefixes. + For example ``. + + Location users to notify can be selected by userCategories or user ID's provided in the request body. + + Notification types: + + | Type | Descrption | + | :--: | ---------- | + | 1 | Marketing | + | 3 | Rules | + | 4 | Bots default | + | 6 | New account creation follow-up | + | 7 | Device alert | + | 8 | App default | + | 11 | Account issues | + | 13 | OAuth client | + | 16 | Device firmware update | + | 17 | SMS chat | + | 18 | Location | + | 19 | Bot error | + | 20 | Badge | + | 22 | Bot report | + | 23 | Message | tags: - User Communications security: - - botApiKey: [] + - userApiKey: [] + parameters: + - name: userId + in: query + description: Send a notification to this user by an administrator + schema: + type: integer + - name: locationId + in: query + description: Send a notification to users on this location + schema: + type: integer + - name: organizationId + in: query + description: Use templates of specific organization + schema: + type: integer requestBody: content: application/json: example: - messages: - - messageId: 123 - status: 2 - deliveryDate: '2024-01-01T00:00:00Z' - - messageId: 124 - status: 2 - schedule: 0 15 10 ? * SUN + brand: care + userCategories: + - 1 + - 2 + users: + - 123 + - 234 + - 345 + language: en + pushMessage: + type: 8 + badgeType: 1 + template: directoryName/PushTemplateName.vm + sound: sound.wav + content: Push notification text + smsFallback: true + smsContent: SMS fallback text + title: Title + subtitle: Subtitle + category: Category Name + model: + key0: value0 + key1: value1 + key2: value2 + info: + field0: info0 + field1: info1 + emailMessage: + subject: Subject + html: true + template: directoryName/EmailTemplateName.vm + content: Email message text + model: + key0: value0 + key1: value1 + key2: value2 + attachments: + - name: imageName.jpg + content: /9j/4AAQSkZJRgABAgEAAAAAAAD/4 + contentType: image/jpeg + contentId: inlineImageId + - name: fileName.jpg + deviceFileId: 123456 + contentId: inlineFileId + smsMessage: + categories: + - 0 + - 1 + template: directoryName/SmsTemplateName.vm + content: Sms message text + individual: true + model: + key0: value0 + key1: value1 + key2: value2 + deviceMessage: + deviceId: optional device ID + title: string + text: string + from: string + duration: 0 + icon: string + muted: true + imageUrl: string + image: base64 encoded image schema: type: object properties: - messages: + brand: + type: string + description: Notification template brand + userCategories: type: array + description: Notify location uses of these categories items: - type: object - properties: - messageId: - type: integer - description: Message ID to update - status: - type: integer - description: Message status - deliveryDate: + type: integer + users: + type: array + description: Notify these uses + items: + type: integer + language: + type: string + description: Message language + pushMessage: + type: object + description: Push notification + properties: + type: + type: integer + description: Notification type + badgeType: + type: integer + description: Badge type + template: + type: string + description: Template to generate notification text + sound: + type: string + content: + type: string + description: Notification text + smsFallback: + type: boolean + description: Send SMS, if the user does not have valid notification tokens + smsContent: + type: string + description: Fallback SMS text + title: + type: string + subtitle: + type: string + category: + type: string + model: + type: object + additionalProperties: type: string - description: Date when the status set as deliverd for one-time message or last notification sent for recurring message - schedule: + description: Notification template parameters key/value string map + info: + type: object + additionalProperties: type: string - description: Cron expression for recurring delivery of notifications - required: - - messageId - - status + description: Additional push notification parameters key/value string map + emailMessage: + type: object + description: Email + properties: + subject: + type: string + description: Email subject + html: + type: boolean + description: Send email in HTTP format + template: + type: string + description: Template to generate email text + content: + type: string + description: Email text + model: + type: object + additionalProperties: + type: string + description: Notification template parameters key/value string map + attachments: + type: array + description: Email attachments + items: + type: object + properties: + name: + type: string + description: Attachment name + content: + type: string + description: Attachment Base64 encoded content + contentType: + type: string + description: Attachment content type + contentId: + type: string + description: Inline content ID + deviceFileId: + type: integer + description: Use this device file thumbnail as the content + required: + - name + smsMessage: + type: object + properties: + template: + type: string + description: Template to generate message text + content: + type: string + description: Message text + individual: + type: boolean + description: If this message to be sent to individual users or to a chat group + model: + type: object + additionalProperties: + type: string + description: Notification template parameters key/value string map + deviceMessage: + type: object + description: Message to be delivered to an IoT device + properties: + deviceId: + type: string + title: + type: string + text: + type: string + from: + type: string + duration: + type: integer + icon: + type: string + muted: + type: boolean + imageUrl: + type: string + image: + type: string responses: '200': description: OK @@ -10190,55 +9429,74 @@ paths: example: resultCode: 0 - get: - summary: Get Messages - operationId: Get Messages + summary: Get Notifications + operationId: Get Notifications + description: |- + Delivery types: + + | Delivery | Description | + | :------: | ----------- | + | 1 | Push notification | + | 2 | Email | + | 3 | Outgoing SMS | + | 4 | Incoming SMS | + + Source types: + + | Source | Description | + | :----: | ----------- | + | 0 | External API call | + | 1 | Rule | + | 2 | Bot | + | 4 | Device firmware update | + | 5 | Internal system logic like account issue | + | 6 | Cloud business logic | + | 7 | External incoming message | tags: - User Communications security: - userApiKey: [] parameters: - - name: locationId + - name: userId in: query - description: Location ID - required: true + description: Get notifications for this user by an administrator schema: type: integer - name: startDate in: query - description: Start date to filter by delivery date + description: Start date to select notifications required: true schema: type: string - name: endDate in: query - description: End date to filter by delivery date + description: End date to select notifications. Default is the current date. schema: type: string - - name: appInstanceId + - name: locationId in: query - description: Bot instance ID + description: Get notifications related to this location schema: type: integer - - name: topicId + - name: sourceType in: query - description: Filter by topic + description: Filter by source type schema: - type: string - - name: readStatus + type: integer + - name: deliveryType in: query - description: Filter read or unread messages + description: Filter by delivery type schema: - type: boolean - - name: lang + type: integer + - name: notificationType in: query - description: Preferred message content language + description: Filter by notification type schema: - type: string + type: integer responses: '200': - description: Messages + description: Notifications history content: application/json: schema: @@ -10246,228 +9504,131 @@ paths: properties: resultCode: type: integer - messages: + notifications: type: array items: type: object properties: - messageId: - type: integer - originalMessageId: - type: integer - scheduleType: - type: integer - status: - type: integer - readStatus: - type: boolean - topicId: - type: string - creationDate: + sendDate: type: string - creationDateMs: + sendDateMs: type: integer - deliveryDate: - type: string - deliveryDateMs: + deliveryType: type: integer - appInstanceId: + notificationType: type: integer - userId: + locationId: type: integer - contentKey: + brand: type: string - contentType: - type: integer - contentText: - type: object - mediaUrl: + templateName: type: string - mediaContentType: + language: type: string - question: - type: object - properties: - id: - type: integer - appInstanceId: - type: integer - creationDate: - type: string - creationDateMs: - type: integer - key: - type: string - editable: - type: boolean - question: - type: string - placeholder: - type: string - collection: - type: object - properties: - name: - type: string - description: - type: string - icon: - type: string - media: - type: string - mediaContentType: - type: string - weight: - type: integer - deviceId: - type: string - icon: - type: string - displayType: - type: integer - defaultAnswer: - type: string - answerFormat: - type: string - slider: - type: object - properties: - min: - type: integer - max: - type: integer - inc: - type: integer - minDesc: - type: string - maxDesc: - type: string - unitsDesc: - type: string - sectionTitle: - type: string - sectionId: - type: integer - questionWeight: - type: integer - responseType: - type: integer - responseOptions: - type: array - items: - type: object - properties: - id: - type: integer - text: - type: string - required: - - id - - text - answerStatus: - type: integer - answer: - type: string - answerDate: - type: string - answerDateMs: - type: integer - answerModified: - type: boolean - example: - resultCode: 0 - messages: - - messageId: 123 - originalMessageId: 111 - scheduleType: 0 - status: 3 - readStatus: false - topicId: general - creationDate: '2023-03-04T12:12:12-07:00' - creationDateMs: 1646537712000 - deliveryDate: '2023-04-04T12:12:12-07:00' - deliveryDateMs: 1656537712000 - appInstanceId: 456 - userId: 345 - contentKey: Short content description - contentType: 2 - contentText: - en: Hi - es: Hola - mediaUrl: https://s3.amazon.com/images/picture.png - mediaContentType: image/png - question: - id: 50234 - appInstanceId: 67 - creationDate: '2023-03-04T12:12:12-07:00' - creationDateMs: 1646537712000 - key: Question key - editable: true - question: What do you think of this question? - placeholder: Some hint - collection: - name: Urgent questions - description: Some description - icon: Icon name - media: Reference to media - mediaContentType: image/jpeg - weight: 10 - deviceId: optional_device_id - icon: optional_icon_name - displayType: 0 - defaultAnswer: '1000' - answerFormat: ^\d{4}$ - slider: - min: 0 - max: 100 - inc: 5 - minDesc: min value description - maxDesc: max value description - unitsDesc: UOM description - sectionTitle: Main questions - sectionId: 2 - questionWeight: 3 - responseType: 4 - responseOptions: - - id: 0 - text: Red - - id: 1 - text: Yellow - answerStatus: 4 - answer: This is some text input - answerDate: '2016-03-04T12:12:12-07:00' - answerDateMs: 1446539712000 - answerModified: false + sound: + type: string + badge: + type: integer + sentCount: + type: integer + sourceType: + type: integer + sourceId: + type: integer + messageText: + type: string + example: + resultCode: 0 + notifications: + - sendDate: '2018-06-12T12:24:48Z' + sendDateMs: 1419137929000 + deliveryType: 1 + notificationType: 7 + locationId: 123 + brand: care + templateName: alert/motion_detected.vm + language: en + sound: default + badge: 1 + sentCount: 3 + sourceType: 6 + sourceId: 1234 + messageText: Motion detected on your camera - /cloud/json/messageRead: - put: - summary: Update Message Read Status - operationId: Update Message Read Status - description: A user can mark a message as read or unread. + /cloud/json/ticket: + post: + summary: Post Support Ticket + operationId: Post Support Ticket + description: |- + Create a support ticket. + + | Type | Details | + | :--: | ------- | + | 1 | problem | + | 2 | incident | + | 3 | question | + | 4 | task | + + Ticket priority is from 1 (low) to 4 (urgent). + + The request is executed asynchronously. The user will be notified about created ticket. tags: - User Communications security: - userApiKey: [] parameters: - - name: locationId + - name: userId in: query - description: Location ID - required: true + description: Request support for this user by an administrator schema: type: integer - - name: messageId + - name: locationId in: query - description: Message ID - required: true + description: Request support for this location schema: type: integer - - name: readStatus - in: query - description: Read status - required: true - schema: - type: boolean + requestBody: + content: + application/json: + example: + brand: family + lang: en + ticket: + type: 1 + priority: 3 + subject: Nice feature + comment: May I ask you to add a new feature to the app? + customFields: + - id: 123 + value: abc + schema: + type: object + properties: + brand: + type: string + lang: + type: string + ticket: + type: object + properties: + type: + type: integer + priority: + type: integer + subject: + type: string + comment: + type: string + customFields: + type: array + items: + type: object + properties: + id: + type: integer + value: + type: string responses: '200': description: OK @@ -10482,213 +9643,250 @@ paths: resultCode: 0 - /cloud/json/questions: - get: - summary: Get Bot Questions - operationId: Get Bot Questions - description: |- - Questions enable bidirectional conversations to take place between the users' location and data analytics services. - Questions enable the user to add context to the data. - - ### Collection - - | Name | Type | Description | - | ---- | :--: | ----------- | - | name | string | A unique name for referencing this collection. | - | mlName | string map | Multiligual name of the collection. | - | description | string | The titles of the group in various languages. | - | mlDescription | string map | Multilingual title of the collection. | - | icon | string | Icon to show next to the collection, if any.| - | iconFont | string | Icon font. | - | weight | integer | The weight of the collection | - | media | string | Media object to display for the collection. | - | mediaContentType | string | The content type of the media object. | - - ### Question - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
idintegerQuestion ID assigned by the system
keystringUnique key to identify this context of this question later, regardless of the description or language of the question itself.
appInstanceIdintegerThe bot instance ID, that asks the question.
creationDateMsmillisecondsCreation timestamp
questionstringThe actual text of the question to ask.
placeholderstringA placeholder for this question.
editablebooleanIf the message is editable, then that means it will show up in a place in the bot where the user can reconfigure the question later. - This is typically used by bots to enable a UI for settings to configure the bot through questions.
responseTypeintegerThe type of question (see below)
displayTypeintegerApplication-layer display type for each type of question (for example, yes/no vs. on/off switch, or a slider that shows integers vs. a slider that shows minutes:seconds)
deviceIdstringName of the device ID referenced by this question, if any.
iconstringIcon to show next to the question, if any.
mediastringReference to some kind of S3 media to play/associate with the question.
defaultAnswerstringPre-populated default values for question responses, or force-change the user's response.
answerFormatstringRegular expression to validate answer format in UI.
sliderstructure - - - - - - - -
minSlider question minimum value
maxSlider question maximum value
incSlider question incremental slider value
minDescDescription of slider question minimum value
maxDescDescription of slider question maximum value
unitsDescDescription of slider question UOM
-
sectionTitlestringThe title of a group of questions
sectionIdintegerThe ID of a group of questions, and the order in which to display this group
questionWeightintegerThe position of a single question within a group. The higher the weight, the lower down on the list the question appears relative to other questions
statusintegerQuestion status: -
0 - replaced by a new question (of the same key) -
2 - available, waiting for an answer -
3 - skipped, the user is going to answer it later -
4 - answered -
5 - no answer, the user is not going to answer on it -
answerStatusintegerThe same as status (used for backward compatibility)
answerstringUser's answer: - * Boolean: 0 = No, 1 = Yes - * Multi-choice Single-select: ID of the radio button - * Multi-choice Multi-select: Bitmask representing response options - * Slider value - * Text entered by the user - - Days of the week are represented by a bitmask: - - 1 - Sunday (1 << 0)
- 2 - Monday (1 << 1)
- 4 - Tuesday (1 << 2)
- 8 - Wednesday (1 << 3)
- 16 - Thursday (1 << 4)
- 32 - Friday (1 << 5)
- 64 - Saturday (1 << 6)
-
answerDatestringWhen the user has answered this question.
answerModifiedbooleanIndicate if the original answer has been modified by other user.
collectionNamestringThe name of collection the question belongs to (can be null).
- - ### Response Types - - - - - - - - - - - - - - - - - - -
Response Type IDNameDisplay Type Definitions
1Boolean
0 = False
1 = True		0 = On/Off Switch - default.
- 1 = Yes/No.
- 2 = Single 'Yes' button only, the question's default value is applied to the button's text. Used to trigger bot actions from the UI.
- 3 = Thumbs-up / Thumbs-down

- The answer is a 0 or 1.
2Multiple choice - Single select0 = Radio buttons - default.
- A list of radio buttons. Requires the "responses" array to list the possible responses. - Users can only select one response. Available for anonymous aggregated public reporting.

- 1 = Drop-down list / Picker.
- A drop down list. Same as radio buttons, but can contain more items.

- 2 = Slider.
- Slider UI view with predefined stops as an options.

- 3 = Modal Bottom Action Sheet.
- Multiple-choice buttons that slide up from the bottom of the screen.

- The answer is the ID of the response option.
4Multiple choice - Multiple selectA list of checkbox options. Requires the "responses" array to list the possible responses. - Users can select multiple responses. Available for anonymous aggregated public reporting.

- The answer is a bitmask of selected choices.
6Day of the weekDay of the week input. - The UI can optimize itself for selecting days of the week [Sun][XXX][Tue][Wed][Thu][XXX][Sat].

- 0 = Select multiple days simultaneously.
- 1 = Pick a single day only.

- The answer is a bitmasked value, days can be logically-OR'd together to specify multiple days of the week, ranging from SUN=0x1 to SAT=0x40.
7Slider0 = Integer select - default.
- Slider, with a defined minimum and maximum.
- By default, minimum = 0 and maximum = 100.
- 1 = Floating point select.
- 2 = Minutes:Seconds.

- Answer is the number selected. For time, the answer is in integer seconds.
8Time in seconds since midnight0 = hours:minutes:seconds (am|pm) - default.
- This accesses the native UI method of declaring a time.
- 1 = hours:minutes (am|pm).

- The answer is in integer seconds since midnight.
9Date and Time in ISO 86010 = Date and time.
- 1 = Date only.

- The answer is in ISO 8601 format, `YYYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm]`
10Text boxOpen-ended question.
- For example, if you were to ask, "Who just walked by the camera?"

- The answer is a string of text.
- - ### Response Options - - | Name | Type | Description | - | ---- | :--: | ----------- | - | id | integer | ID number for types of questions that feature a list of options | - | text | string | String for an option on a type of question that features a list of options | - - Retrieve requested questions. - - For an individual user, there should be at most one unanswered question available per day, unless the question is urgent. + /cloud/json/feedback: + post: + summary: Post Crowd Feedback + operationId: Post Crowd Feedback + description: |- + Crowd feedback is first delivered to a support email for moderation. + If the feedback is unique, then the support staff will make it public for other users to vote on. + + The API returns the created feedback record ID and if a ticket has been created in a support cloud, then the ticket ID and the brand name. tags: - - Questions + - User Communications security: - userApiKey: [] parameters: - - name: locationId + - name: userId in: query - description: Location ID to get questions - required: true + description: Send a feedback for this user by an administrator schema: type: integer - - name: answerStatus + - name: brand in: query - description: >- - Return questions with requested answer statuses. - By default questions with statuses 2 and 3 are returned. - Multiple values are supported. + description: Application brand + schema: + type: string + requestBody: + content: + application/json: + example: + feedback: + appName: Care + appVersion: 2.0.1 + type: 1 + subject: Nice feature + email: john@mail.com + deviceId: ABC123 + deviceModel: iPhone + deviceOs: 7.0.4 + productId: 123 + productCategory: 2200 + viewer: Android Samsung S3 + description: It would be best if the app will be able to .. + schema: + type: object + properties: + feedback: + type: object + properties: + appName: + type: string + description: Unique name / identifier of the app or product, selected by the developer + appVersion: + type: string + description: Version of the app that generated this request + type: + type: integer + enum: [1,2] + description: >- + 1 - New feature request +
2 - Problem report + subject: + type: string + description: Subject line describing the feature or issue + email: + type: string + description: Email address of the user generating this request, not shown publicly. + deviceId: + type: string + description: Problem device ID + deviceModel: + type: string + description: Model of the device that generated the request (i.e. iPhone5,1) + deviceOs: + type: string + description: Operating system on the device that generated the request (i.e. iOS 8.1.2) + productId: + type: integer + description: Product ID, present if the user is giving feedback on a specific type of product. + productCategory: + type: integer + description: Category of the product, present if the user is giving feedback on a specific type of product. + viewer: + type: string + description: Viewer description + description: + type: string + description: |- + "I want the product to also do ..." + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + feedbackId: + type: integer + brand: + type: string + ticketId: + type: integer + example: + resultCode: 0 + feedbackId: 123 + brand: care + ticketId: 12345 + + + /cloud/json/feedback/{appName}/{type}: + get: + summary: Get Crowd Feedback by Searching + operationId: Get Crowd Feedback by Searching + tags: + - User Communications + security: + - userApiKey: [] + parameters: + - name: appName + in: path + description: Unique name / identifier of the app or product, selected by the developer + required: true + schema: + type: string + - name: type + in: path + description: 1 - New feature request
2 - Problem report + required: true schema: type: integer - - name: editable + enum: [1,2] + - name: startPos in: query - description: |- - Filter answered questions: -
true - return only editable answered questions, -
false - return only not editable answered questions, -
otherwise return all answered questions. + description: Index of the first record to be returned. schema: - type: boolean - - name: collectionName + type: integer + - name: length in: query - description: Questions collection name filter + description: Number of records to return. + required: true schema: - type: string - - name: questionId + type: integer + - name: productId in: query - description: Extract a specific question ID. + description: Filter the response by product ID. You may include multiple of these parameters to filter by multiple product IDs. schema: type: integer - - name: appInstanceId + - name: productCategory in: query - description: Only retrieve questions for a specific bot. + description: Filter the response by product category. You may include multiple of these parameters to filter by multiple product categories. schema: type: integer - - name: lang + - name: disabled in: query - description: Questions text language. If not set, user's or default language will be used. + description: Return not enabled feedbacks as well. schema: - type: string - - name: limit - in: query - description: Maximum number of questions to return. The default is unlimited. + type: boolean + responses: + '200': + description: Feedbacks + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + feedbacks: + type: array + items: + type: object + properties: + id: + type: integer + appName: + type: string + appVersion: + type: string + type: + type: integer + subject: + type: string + email: + type: string + deviceId: + type: string + deviceModel: + type: string + deviceOs: + type: string + productId: + type: integer + productCategory: + type: integer + viewer: + type: string + description: + type: string + votingCount: + type: integer + rank: + type: integer + enabled: + type: boolean + example: + resultCode: 0 + feedbacks: + - id: 123 + appName: Care + appVersion: 2.0.1 + type: 1 + subject: Nice feature + email: john@mail.com + deviceId: ABC123 + deviceModel: iPhone + deviceOs: 7.0.4 + productId: 123 + productCategory: 2200 + viewer: Android Samsung S3 + description: It would be best if the app will be able to .. + votingCount: 10 + rank: 1 + enabled: true + + + /cloud/json/feedback/{feedbackId}: + get: + summary: Get Specific Crowd Feedback + operationId: Get Specific Crowd Feedback + tags: + - User Communications + security: + - userApiKey: [] + parameters: + - name: feedbackId + in: path + description: Specific feedback ID + required: true schema: type: integer responses: '200': - description: Questions + description: Feedback content: application/json: schema: @@ -10696,216 +9894,147 @@ paths: properties: resultCode: type: integer - questions: + feedbacks: type: array items: type: object properties: id: type: integer - appInstanceId: - type: integer - creationDate: + appName: + type: string + appVersion: type: string - creationDateMs: + type: type: integer - key: - type: string - editable: - type: boolean - question: + subject: type: string - placeholder: + email: type: string - collection: - type: object - properties: - name: - type: string - mlName: - type: object - additionalProperties: - type: string - description: Multilingual string map - description: - type: string - mlDescription: - type: object - additionalProperties: - type: string - description: Multilingual string map - icon: - type: string - iconFont: - type: string - media: - type: string - mediaContentType: - type: string - weight: - type: integer deviceId: type: string - icon: - type: string - displayType: - type: integer - defaultAnswer: - type: string - answerFormat: + deviceModel: type: string - slider: - type: object - properties: - min: - type: integer - max: - type: integer - inc: - type: integer - minDesc: - type: string - maxDesc: - type: string - unitsDesc: - type: string - sectionTitle: + deviceOs: type: string - sectionId: - type: integer - questionWeight: - type: integer - responseType: + productId: type: integer - responseOptions: - type: array - items: - type: object - properties: - id: - type: integer - text: - type: string - required: - - id - - text - answerStatus: + productCategory: type: integer - answer: + viewer: type: string - answerDate: + description: type: string - answerDateMs: + votingCount: type: integer - answerModified: + rank: + type: integer + enabled: type: boolean example: resultCode: 0 - questions: - - id: 50234 - appInstanceId: 67 - creationDate: '2016-03-04T12:12:12-07:00' - creationDateMs: 1446537712000 - key: Question key - editable: true - question: What do you think of this question? - placeholder: Some hint - collection: - name: Urgent questions - mlName: - en: Urgent questions - description: Some description - mlDescription: - en: Collection description - icon: Icon name - iconFont: Icon font - media: Reference to media - mediaContentType: image/jpeg - weight: 10 - deviceId: optional_device_id - icon: optional_icon_name - displayType: 0 - defaultAnswer: '1000' - answerFormat: ^\d{4}$ - slider: - min: 0 - max: 100 - inc: 5 - minDesc: min value description - maxDesc: max value description - unitsDesc: UOM description - sectionTitle: Main questions - sectionId: 2 - questionWeight: 3 - responseType: 4 - responseOptions: - - id: 0 - text: Red - - id: 1 - text: Yellow - answerStatus: 4 - answer: This is some text input - answerDate: '2016-03-04T12:12:12-07:00' - answerDateMs: 1446539712000 - answerModified: false - - put: - summary: Answer Bot Questions - operationId: Answer Bot Questions - description: |- - After answering a question, if the question is aggregated publicly then the user should also see how other people voted. - - A user can skip the question or prefer to not answer it by setting the corresponding answer status. - - Providing just the question ID the UI app can mark the question as notified. - - Only editable questions can be updated later. - Typically editable questions are used to configure Composer Apps and add further context to the user's data later. + feedbacks: + - id: 123 + appName: Care + appVersion: 2.0.1 + type: 1 + subject: Nice feature + email: john@mail.com + deviceId: ABC123 + deviceModel: iPhone + deviceOs: 7.0.4 + productId: 123 + productCategory: 2200 + viewer: Android Samsung S3 + description: It would be best if the app will be able to .. + votingCount: 10 + rank: 1 + enabled: true - The user's tagged attributes should migrate with the question, such that when a new answer is selected, - any previous tags are removed and new tags are applied. - The body and response is designed to handle answers to multiple questions simultaneously. + /cloud/json/feedback/{feedbackId}/{rank}: + put: + summary: Vote for Feedback + operationId: Vote for Feedback tags: - - Questions + - User Communications security: - userApiKey: [] parameters: - - name: locationId - in: query - description: Location ID to answer questions + - name: feedbackId + in: path + description: Feedback ID to vote on required: true schema: type: integer + - name: rank + in: path + description: 'Rank: 1 to cast a vote, 0 to remove a vote.' + required: true + schema: + type: integer + responses: + '200': + description: OK + headers: {} + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + + /cloud/json/support: + post: + summary: Request Support + operationId: Request Support + description: If a ticket has been created in a support cloud, then the API returns the ticket ID and the brand name. + tags: + - User Communications + parameters: + - name: brand + in: query + description: Brand of the support request templates + schema: + type: string requestBody: content: application/json: example: - questions: - - id: 50234 - answer: true - - id: 56236 - answerStatus: 3 - - id: 56237 + firstName: John + lastName: Smith + email: john.smith@example.com + subject: Subject text + text: Comments or questions + subscribe: This user wants to subscribe to XYZ schema: type: object properties: - questions: - type: array - items: - type: object - properties: - id: - type: integer - answer: - type: string - answerStatus: - type: integer - required: - - id + firstName: + type: string + description: First name (what do your friends call you?) + lastName: + type: string + description: Last name + email: + type: string + description: Reply email address + subject: + type: string + description: Subject line, short description of the issue + text: + type: string + description: The actual comments from the user + subscribe: + type: string + description: Text describing whether or not the user wants to subscribe to newsletters, etc. It's a manual process on the backend. responses: '200': - description: Answered questions + description: OK content: application/json: schema: @@ -10913,102 +10042,39 @@ paths: properties: resultCode: type: integer - questions: - type: array - items: - type: object - properties: - id: - type: integer - answerStatus: - type: integer - answer: - type: string - answerDate: - type: string - answerDateMs: - type: integer - answerModified: - type: boolean - required: - - id - - answerStatus - - answerDate - - answerDateMs - - answerModified - - answer + brand: + type: string + ticketId: + type: integer example: resultCode: 0 - questions: - - id: 50234 - answerStatus: 4 - answer: 'true' - answerDate: '2016-03-04T12:12:12-07:00' - answerDateMs: 1446539712000 - answerModified: false - - id: 56234 - answerStatus: 3 - answerDate: '2016-03-04T12:12:12-07:00' - answerDateMs: 1446539712000 - answerModified: true - - id: 56237 - answerStatus: 4 - answer: default answer - answerDate: '2016-03-04T12:12:12-07:00' - answerDateMs: 1446539712000 - answerModified: false + brand: care + ticketId: 12345 - /cloud/json/surveyAnswers: + /cloud/json/messageTopics: get: - summary: Get Survey Answers - operationId: Get Survey Answers - description: |- - Returns history of survey answers. + summary: Get Message Topics + operationId: Get Message Topics tags: - - Questions + - User Communications security: - userApiKey: [] - botApiKey: [] parameters: - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - - name: userId - in: query - description: User ID filter - schema: - type: integer - - name: surveyKey - in: query - description: Survey filter - schema: - type: string - - name: status + - name: appId in: query - description: |- - Survey answer status filter:
- 0 - Open
- 1 - Closed + description: Bot ID schema: type: integer - enum: [0,1] - - name: startDate - in: query - description: Answers start date - schema: - type: string - - name: endDate + - name: lang in: query - description: Answers end date + description: Preferred content language schema: type: string responses: '200': - description: Survey answers + description: Message Topics content: application/json: schema: @@ -11016,199 +10082,373 @@ paths: properties: resultCode: type: integer - answers: + topics: type: array - description: Survey answer records items: type: object properties: - answerId: - type: integer - description: Answer record ID - status: - type: integer - enum: [0,1] - description: |- - Answer record status:
- 0 - open,
- 1 - closed - userId: - type: integer - description: User ID - locationId: - type: integer - description: Location ID - startDate: - type: string - description: Answering start date - startDateMs: - type: string - description: Answering start time - notificationDate: - type: string - description: Last notificatyion send date - notificationDateMs: - type: string - description: Last notificatyion send time - endDate: + topicId: type: string - description: Answering end date - endDateMs: + name: type: string - description: Answering end time - survey: - type: object - properties: - surveyKey: - type: string - description: Unique Survey Key - organizationId: - type: integer - description: ID of organization, which is the owner of the survey - status: - type: integer - enum: [0,1,2] - description: |- - Survey status:
- 0 - inactive,
- 1 - active,
- 2 - closed - title: - type: string - description: Title - description: - type: string - description: Description + bots: + type: array + items: + type: object + properties: + appId: + type: integer + bundle: + type: string + name: + type: string + author: + type: string + category: + type: string + type: + type: integer + core: + type: integer + required: + - appId + - bundle + - name + - author + - category + - type + - core + required: + - topicId + - name + - bots example: resultCode: 0 - answers: - - answerId: 12345 - status: 1 - userId: 678 - locationId: 456 - startDate: '2026-01-15T09:30:00-07:00' - startDateMs: '1736952600000' - notificationDate: '2026-01-15T09:30:00-07:00' - notificationDateMs: '1736952600000' - endDate: '2026-01-15T10:15:00-07:00' - endDateMs: '1736955300000' - survey: - surveyKey: 'monthly_wellness_check' - organizationId: 100 - status: 1 - title: 'Monthly Wellness Check' - description: 'Regular wellness assessment survey' - - answerId: 12346 - status: 0 - userId: 679 - locationId: 456 - startDate: '2026-01-20T14:00:00-07:00' - startDateMs: '1737406800000' - survey: - surveyKey: 'intake_assessment' - organizationId: 100 - status: 1 - title: 'Patient Intake Assessment' - description: 'Initial patient evaluation survey' + topics: + - topicId: general + name: General + bots: + - appId: 2345 + bundle: com.peoplepowerco.engage + name: My Engage Bot + author: Your Company + category: S,W + type: 0 + core: -1 + - topicId: engage + name: Engage + bots: + - appId: 2345 + bundle: com.peoplepowerco.engage + name: My Engage Bot + author: Your Company + category: S,W + type: 0 + core: -1 + + /cloud/json/messages: post: - summary: Start Answering Survey - operationId: Start Answering Survey + summary: Create Messages + operationId: Create Messages description: |- - Intitiates a survey answering. This API creates a new survey answer record for the requested user or returns an existing answer record. + Message APIs allow to create, schedule, and retrieve messages from AI bots to location users. + + ### Message Statuses + + | Status | Description | + |:------:|------------------------| + | 0 | Initial, storage only | + | 1 | Ready for scheduling | + | 2 | Scheduled for delivery | + | 3 | Delivered | + | 4 | Deleted | + + ### Scheduling Types + + | Type | Description | + |:----:|-------------| + | 0 | One-time | + | 1 | Recurring | - A user or a bot can submit answers to some survey questions in this request. Also question answers can be copied from a previously submitted survey by ID. + One-time messages will be delivered to users only once, when the status is set to `2` or `3`. - The API can send an email to a user or to an organization notification users with a link to answer the survey or to view the existing answers, - if the `sendToUser` or the `botNotificationId` or the `notificationCategory` parameters are provided. + Notifications from recurring messages can be delivered multiple times according to the notification schedule until the maximum delivery date, when the message has the status `2`. - The API returns the answer record with an authentication token and a URL to answer the survey for the user or view the previous answers. + Delivered messages will have status `3`. + + ### Delivery Types + + A message content can be delivered to users over different notification channels. + + | Type | Description | + |:----:|-------------| + | 0 | In-App | + | 1 | Push | + | 2 | Email | + | 3 | SMS | + + A message content with the delivery type `0` "In-App" will be returned from the get message API. + It is always required, when a message is created. + + ### Text Content Types + + | Type | Description | Delivery Types | + |:----:|----------------| -------------- | + | 0 | Text (default) | All | + | 1 | HTML | Email only | + | 2 | Markdown | In-App only | + + AI bots and users can create new messages using this API. + + User messages always have status delivered. tags: - - Questions + - User Communications security: - userApiKey: [] - botApiKey: [] parameters: - name: locationId in: query - description: Answer a survey for this location - required: true - schema: - type: integer - - name: surveyKey - in: query - description: Key of the survey to answer - required: true - schema: - type: string - - name: userId - in: query - description: Answer a survey for this user - required: true - schema: - type: integer - - name: answerId - in: query - description: An existing answer record ID to recreate previous API response and action - schema: - type: integer - - name: preAnswerId - in: query - description: Copy question answers from this answer record - schema: - type: integer - - name: sendToUser - in: query - description: Send the email directly to the user - schema: - type: boolean - - name: botNotificationId - in: query - description: Send the email to organization notification users selected by this notification ID - schema: - type: integer - - name: notificationCategory - in: query - description: Send the email to organization notification users with this category + description: Location ID, when created by a user schema: type: integer requestBody: content: application/json: example: - questions: - - questionKey: Question#1 - answer: '1' - - questionKey: Question#2 - answer: '0' - notificationModel: - connectionDate: 2026-02-02 + messages: + - status: 1 + originalMessageId: 111 + topicId: general + scheduleType: 0 + contentKey: Short content description + contents: + - deliveryType: 0 + contentType: 2 + text: + en: In-App message text + es: ... + - deliveryType: 1 + contentType: 0 + text: + en: Push notification + es: ... + title: Title + subtitle: Subtitle + category: 21.0.1 + sound: sound.wav + - deliveryType: 2 + contentType: 1 + text: + en: Email message text + es: ... + subject: + en: Email subject + es: ... + attachments: + - name: imageName.jpg + content: /9j/4AAQSkZJRgABAgEAAAAAAAD/4 + contentType: image/jpeg + contentId: inlineImageId + - deliveryType: 3 + contentType: 0 + text: + en: SMS text + es: ... + questionId: 987 + mediaUrl: https://s3.amazon.com/images/picture.png + mediaContentType: image/png + maxDeliveryDate: '2024-01-01T00:00:00Z' + deliveryDayTime: 36000 + timeToLive: 3600 + schedule: 0 0 10 ? * SUN + recipients: + - categories: + - 1 + - 2 + roles: + - 1 + - 2 + locationAccess: 10 + - userId: 678 + schema: + type: object + properties: + messages: + type: array + items: + type: object + properties: + status: + type: integer + description: Message status + originalMessageId: + type: integer + description: Top message ID in the messages thread + topicId: + type: string + description: Messages topic ID + scheduleType: + type: integer + description: Scheduling type + contentKey: + type: string + description: Descriptive text used to classify priority of the message, e.g. Fall Event or Dog Walking + contents: + type: array + description: An array of objects with localized message texts by delivery types + items: + type: object + properties: + deliveryType: + type: integer + description: Delivery type + contentType: + type: integer + description: Message text content type + text: + type: object + additionalProperties: + type: string + description: Multilingual message text string map, where the keys are language names + title: + type: string + subtitle: + type: string + category: + type: string + sound: + type: string + subject: + type: object + additionalProperties: + type: string + description: Multilingual subject string map, where the keys are language names + attachments: + type: array + description: Email attachments + items: + type: object + properties: + name: + type: string + content: + type: string + contentType: + type: string + contentId: + type: string + required: + - deliveryType + - contentType + - text + questionId: + type: integer + description: ID of a question associated with this message + mediaUrl: + type: string + description: URL of media object + mediaContentType: + type: string + description: Media object content type, e.g. image/png + maxDeliveryDate: + type: string + description: Maximum absolute time by which the message has to be delivered + deliveryDayTime: + type: integer + description: Time of the day in seconds at which the message should be delivered + timeToLive: + type: integer + description: Time in seconds from the delivery date to count the message as active for replies by SMS + schedule: + type: string + description: Cron expression for recurring delivery of notifications + recipients: + type: array + description: An array of citeria to select notification recipients + items: + type: object + properties: + categories: + type: array + items: + type: integer + roles: + type: array + items: + type: integer + locationAccess: + type: integer + userId: + type: integer + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + messages: + type: array + items: + type: object + properties: + messageId: + type: integer + example: + resultCode: 0 + messages: + - messageId: 123 + + put: + summary: Update Messages + operationId: Update Messages + description: AI bots can update message statuses and schedule delivery time. + tags: + - User Communications + security: + - botApiKey: [] + requestBody: + content: + application/json: + example: + messages: + - messageId: 123 + status: 2 + deliveryDate: '2024-01-01T00:00:00Z' + - messageId: 124 + status: 2 + schedule: 0 15 10 ? * SUN schema: type: object properties: - questions: + messages: type: array - description: Optional answers to the survey questions items: type: object properties: - questionKey: + messageId: + type: integer + description: Message ID to update + status: + type: integer + description: Message status + deliveryDate: type: string - description: Question key - answer: + description: Date when the status set as deliverd for one-time message or last notification sent for recurring message + schedule: type: string - description: Question answer + description: Cron expression for recurring delivery of notifications required: - - questionKey - - answer - notificationModel: - type: object - additionalProperties: - type: string - description: Additional notification template parameters as a string map + - messageId + - status responses: '200': - description: Survey Answer + description: OK content: application/json: schema: @@ -11216,95 +10456,58 @@ paths: properties: resultCode: type: integer - answer: - description: Survey answer record - type: object - properties: - answerId: - type: integer - description: Answer record ID - status: - type: integer - enum: [0,1] - description: |- - Answer record status:
- 0 - open,
- 1 - closed - userId: - type: integer - description: User ID - locationId: - type: integer - description: Location ID - startDate: - type: string - description: Answering start date - startDateMs: - type: string - description: Answering start time - notificationDate: - type: string - description: Last notificatyion send date - notificationDateMs: - type: string - description: Last notificatyion send time - endDate: - type: string - description: Answering end date - endDateMs: - type: string - description: Answering end time - token: - type: string - description: Answer the survey authentication token - surveyUrl: - type: string - description: Answer the survey URL example: resultCode: 0 - answer: - answerId: 12345 - status: 1 - userId: 678 - locationId: 456 - startDate: '2026-01-15T09:30:00-07:00' - startDateMs: '1736952600000' - notificationDate: '2026-01-15T09:30:00-07:00' - notificationDateMs: '1736952600000' - endDate: '2026-01-15T10:15:00-07:00' - endDateMs: '1736955300000' - token: abc.def.ghijklm - surveyUrl: https://app.caredaily.ai/espapi/redirect/survey/abc.def.ghijklm - /cloud/json/surveyQuestions: get: - summary: Get Survey Questions - operationId: Get Survey Questions - description: |- - Return open organization survey details, sections, questions, and previously submitted answers. - - The request can be authenticated either by a survey answer token (Bearer JWT) or by a user or bot API key. + summary: Get Messages + operationId: Get Messages tags: - - Questions + - User Communications security: - - surveyAnswerAuth: [] - userApiKey: [] - - botApiKey: [] parameters: - name: locationId in: query - description: Location ID when a user or a bot is authenticated + description: Location ID + required: true schema: type: integer - - name: answerId + - name: startDate in: query - description: Answer ID when a user or a bot is authenticated + description: Start date to filter by delivery date + required: true + schema: + type: string + - name: endDate + in: query + description: End date to filter by delivery date + schema: + type: string + - name: appInstanceId + in: query + description: Bot instance ID schema: type: integer + - name: topicId + in: query + description: Filter by topic + schema: + type: string + - name: readStatus + in: query + description: Filter read or unread messages + schema: + type: boolean + - name: lang + in: query + description: Preferred message content language + schema: + type: string responses: '200': - description: Survey Questions + description: Messages content: application/json: schema: @@ -11312,279 +10515,228 @@ paths: properties: resultCode: type: integer - survey: - type: object - properties: - surveyKey: - type: string - description: Survey Key - organizationId: - type: integer - description: ID of organization, which is the owner of the survey - status: - type: integer - enum: [0,1,2] - description: |- - Survey status:
- 0 - inactive,
- 1 - active,
- 2 - closed - answerStatus: - type: integer - enum: [0,1] - description: |- - Survey answer status:
- 0 - open to submit answers
- 1 - closed - title: - type: string - description: Title - description: - type: string - description: Description - instructions: - type: string - description: Answer Instructions - pagination: - type: boolean - description: Pagination flag to display survey in UI by pages - startDate: - type: string - description: Answering process start date - startDateMs: - type: integer - description: Answering process start time - notificationDate: - type: string - description: The last notification send date - notificationDateMs: - type: integer - description: The last notification send time - sections: - type: array - items: + messages: + type: array + items: + type: object + properties: + messageId: + type: integer + originalMessageId: + type: integer + scheduleType: + type: integer + status: + type: integer + readStatus: + type: boolean + topicId: + type: string + creationDate: + type: string + creationDateMs: + type: integer + deliveryDate: + type: string + deliveryDateMs: + type: integer + appInstanceId: + type: integer + userId: + type: integer + contentKey: + type: string + contentType: + type: integer + contentText: + type: object + mediaUrl: + type: string + mediaContentType: + type: string + question: type: object properties: - sectionId: + id: type: integer - description: Section ID - orderNum: + appInstanceId: type: integer - description: Ordering number within the survey or the parent section - title: + creationDate: type: string - description: Optinal section title - description: + creationDateMs: + type: integer + key: type: string - description: Section description - questions: + editable: + type: boolean + question: + type: string + placeholder: + type: string + collection: + type: object + properties: + name: + type: string + description: + type: string + icon: + type: string + media: + type: string + mediaContentType: + type: string + weight: + type: integer + deviceId: + type: string + icon: + type: string + displayType: + type: integer + defaultAnswer: + type: string + answerFormat: + type: string + slider: + type: object + properties: + min: + type: integer + max: + type: integer + inc: + type: integer + minDesc: + type: string + maxDesc: + type: string + unitsDesc: + type: string + sectionTitle: + type: string + sectionId: + type: integer + questionWeight: + type: integer + responseType: + type: integer + responseOptions: type: array items: type: object properties: - questionKey: - type: string - description: Question key uniqie within the survey - orderNum: - type: integer - description: Ordering number within the the section - question: - type: string - description: Question text - description: - type: string - description: Question description - responseType: - type: integer - description: Answer type - optional: - type: boolean - description: If the answer is optional to submit the survey - displayType: + id: type: integer - description: UI display type for each type of answer (for example, yes/no vs. on/off switch, or a slider that shows integers vs. a slider that shows minutes:seconds) - answerFormat: - type: string - description: Regular expression to validate answer format in UI. - slider: - type: object - description: Slider - properties: - min: - type: integer - description: Answer minimum value - max: - type: integer - description: Answer maximum value - inc: - type: integer - description: Slider increment - minDesc: - type: string - description: Description of slider minimum value - maxDesc: - type: string - description: Description of slider maximum value - unitsDesc: - type: string - description: Unit description - responseOptions: - type: array - description: - items: - type: object - properties: - id: - type: integer - description: ID number for types of questions that feature a list of options - text: - type: string - description: Description of the option - required: - - id - - text - answer: - type: string - description: Previous answer value - answerDate: - type: string - description: Previous answer date - answerDateMs: + text: type: string - description: Previous answer time + required: + - id + - text + answerStatus: + type: integer + answer: + type: string + answerDate: + type: string + answerDateMs: + type: integer + answerModified: + type: boolean example: resultCode: 0 - survey: - surveyKey: ConnectionSurvey - organizationId: 100 - status: 1 - answerStatus: 0 - title: Connections Survey - description: Successful Aging Connections Questionnaire - instructions: Please answer all questions honestly - pagination: true - startDate: '2026-01-15T09:30:00-07:00' - startDateMs: 1736952600000 - notificationDate: '2026-01-15T09:30:00-07:00' - notificationDateMs: 1736952600000 - sections: - - sectionId: 1 - orderNum: 1 - title: Personal Information - questions: - - questionKey: age_range - orderNum: 1 - question: What is your age range? - description: Select the range that includes your current age - responseType: 4 - optional: false - displayType: 1 - responseOptions: - - id: 1 - text: 18-30 - - id: 2 - text: 31-50 - - id: 3 - text: 51-70 - - id: 4 - text: 71+ - - questionKey: living_alone - orderNum: 2 - question: Do you live alone? - responseType: 1 - optional: false - displayType: 1 - answer: 'true' - answerDate: '2026-01-15T10:00:00-07:00' - answerDateMs: '1736954400000' - - sectionId: 2 - orderNum: 2 - title: Health Assessment - questions: - - questionKey: pain_level - orderNum: 1 - question: Rate your current pain level - description: Use the slider to indicate your pain level - responseType: 2 - optional: false - displayType: 2 - slider: - min: 0 - max: 10 - inc: 1 - minDesc: No pain - maxDesc: Severe pain - unitsDesc: points - - questionKey: medication_notes - orderNum: 2 - question: Any notes about your medications? - responseType: 3 - optional: true - displayType: 1 - answerFormat: '^.{0,500}$' + messages: + - messageId: 123 + originalMessageId: 111 + scheduleType: 0 + status: 3 + readStatus: false + topicId: general + creationDate: '2023-03-04T12:12:12-07:00' + creationDateMs: 1646537712000 + deliveryDate: '2023-04-04T12:12:12-07:00' + deliveryDateMs: 1656537712000 + appInstanceId: 456 + userId: 345 + contentKey: Short content description + contentType: 2 + contentText: + en: Hi + es: Hola + mediaUrl: https://s3.amazon.com/images/picture.png + mediaContentType: image/png + question: + id: 50234 + appInstanceId: 67 + creationDate: '2023-03-04T12:12:12-07:00' + creationDateMs: 1646537712000 + key: Question key + editable: true + question: What do you think of this question? + placeholder: Some hint + collection: + name: Urgent questions + description: Some description + icon: Icon name + media: Reference to media + mediaContentType: image/jpeg + weight: 10 + deviceId: optional_device_id + icon: optional_icon_name + displayType: 0 + defaultAnswer: '1000' + answerFormat: ^\d{4}$ + slider: + min: 0 + max: 100 + inc: 5 + minDesc: min value description + maxDesc: max value description + unitsDesc: UOM description + sectionTitle: Main questions + sectionId: 2 + questionWeight: 3 + responseType: 4 + responseOptions: + - id: 0 + text: Red + - id: 1 + text: Yellow + answerStatus: 4 + answer: This is some text input + answerDate: '2016-03-04T12:12:12-07:00' + answerDateMs: 1446539712000 + answerModified: false + + /cloud/json/messageRead: put: - summary: Answer Survey Questions - operationId: Answer Survey Questions - description: |- - Put survey answers by a Survey API key to the latest open survey response. - A user can submit a portion of answers in one API call. Some of answers can overwrite previous. - - The API checks, if the survey is not answered yet by the user (withing configured date interval). - - An optional parameter `status` is used to finalize the latest survey response. - In this case the API checks that all questions answered and triggers bots. - - The request can be authenticated either by a survey answer token (Bearer JWT) or by a user or bot API key. + summary: Update Message Read Status + operationId: Update Message Read Status + description: A user can mark a message as read or unread. tags: - - Questions + - User Communications security: - - surveyAnswerAuth: [] - userApiKey: [] - - botApiKey: [] parameters: - name: locationId in: query - description: Location ID when a user or a bot is authenticated + description: Location ID + required: true schema: type: integer - - name: answerId + - name: messageId in: query - description: Answer ID when a user or a bot is authenticated + description: Message ID + required: true schema: type: integer - - name: status + - name: readStatus in: query - description: |- - Change survey response status: 1 - close + description: Read status + required: true schema: - type: integer - requestBody: - content: - application/json: - example: - questions: - - questionKey: Question#1 - answer: '1' - - questionKey: Question#2 - answer: '0' - schema: - type: object - properties: - questions: - type: array - items: - type: object - properties: - questionKey: - type: string - description: Question key - answer: - type: string - description: Question answer - required: - - questionKey - - answer + type: boolean responses: '200': description: OK @@ -11599,71 +10751,213 @@ paths: resultCode: 0 - /cloud/json/systemProperty/{propertyName}: + /cloud/json/questions: get: - summary: Get User or System Property - operationId: Get User or System Property + summary: Get Bot Questions + operationId: Get Bot Questions description: |- - This API will first attempt to return a user-specific property value in plain text. - If there is no user-specific property set, it will attempt to return a system-wide property value as plain text. - If there is no system property available, it will return no content. + Questions enable bidirectional conversations to take place between the users' location and data analytics services. + Questions enable the user to add context to the data. - When using the returned content in your code, be sure to check for edge cases where no content was retrieved, - or the value is out-of-bounds, or the value was not the right type of information your code expects. + ### Collection + + | Name | Type | Description | + | ---- | :--: | ----------- | + | name | string | A unique name for referencing this collection. | + | mlName | string map | Multiligual name of the collection. | + | description | string | The titles of the group in various languages. | + | mlDescription | string map | Multilingual title of the collection. | + | icon | string | Icon to show next to the collection, if any.| + | iconFont | string | Icon font. | + | weight | integer | The weight of the collection | + | media | string | Media object to display for the collection. | + | mediaContentType | string | The content type of the media object. | - When retrieving a system property, the API key is optional. - When the API key is not presented, the API will always return a System Property and never override it with a User Property of the same name. - tags: - - System and User Properties - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: propertyName - in: path - description: Name of the property value to retrieve, i.e. "ppc.api.debug_level" - required: true - schema: - type: string - responses: - '200': - description: Property value - content: - text/plain: - example: | - DEBUG + ### Question + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
idintegerQuestion ID assigned by the system
keystringUnique key to identify this context of this question later, regardless of the description or language of the question itself.
appInstanceIdintegerThe bot instance ID, that asks the question.
creationDateMsmillisecondsCreation timestamp
questionstringThe actual text of the question to ask.
placeholderstringA placeholder for this question.
editablebooleanIf the message is editable, then that means it will show up in a place in the bot where the user can reconfigure the question later. + This is typically used by bots to enable a UI for settings to configure the bot through questions.
responseTypeintegerThe type of question (see below)
displayTypeintegerApplication-layer display type for each type of question (for example, yes/no vs. on/off switch, or a slider that shows integers vs. a slider that shows minutes:seconds)
deviceIdstringName of the device ID referenced by this question, if any.
iconstringIcon to show next to the question, if any.
mediastringReference to some kind of S3 media to play/associate with the question.
defaultAnswerstringPre-populated default values for question responses, or force-change the user's response.
answerFormatstringRegular expression to validate answer format in UI.
sliderstructure + + + + + + + +
minSlider question minimum value
maxSlider question maximum value
incSlider question incremental slider value
minDescDescription of slider question minimum value
maxDescDescription of slider question maximum value
unitsDescDescription of slider question UOM
+
sectionTitlestringThe title of a group of questions
sectionIdintegerThe ID of a group of questions, and the order in which to display this group
questionWeightintegerThe position of a single question within a group. The higher the weight, the lower down on the list the question appears relative to other questions
statusintegerQuestion status: +
0 - replaced by a new question (of the same key) +
2 - available, waiting for an answer +
3 - skipped, the user is going to answer it later +
4 - answered +
5 - no answer, the user is not going to answer on it +
answerStatusintegerThe same as status (used for backward compatibility)
answerstringUser's answer: + * Boolean: 0 = No, 1 = Yes + * Multi-choice Single-select: ID of the radio button + * Multi-choice Multi-select: Bitmask representing response options + * Slider value + * Text entered by the user + Days of the week are represented by a bitmask: + + 1 - Sunday (1 << 0)
+ 2 - Monday (1 << 1)
+ 4 - Tuesday (1 << 2)
+ 8 - Wednesday (1 << 3)
+ 16 - Thursday (1 << 4)
+ 32 - Friday (1 << 5)
+ 64 - Saturday (1 << 6)
+
answerDatestringWhen the user has answered this question.
answerModifiedbooleanIndicate if the original answer has been modified by other user.
collectionNamestringThe name of collection the question belongs to (can be null).
+ + ### Response Types + + + + + + + + + + + + + + + + + + +
Response Type IDNameDisplay Type Definitions
1Boolean
0 = False
1 = True		0 = On/Off Switch - default.
+ 1 = Yes/No.
+ 2 = Single 'Yes' button only, the question's default value is applied to the button's text. Used to trigger bot actions from the UI.
+ 3 = Thumbs-up / Thumbs-down

+ The answer is a 0 or 1.
2Multiple choice - Single select0 = Radio buttons - default.
+ A list of radio buttons. Requires the "responses" array to list the possible responses. + Users can only select one response. Available for anonymous aggregated public reporting.

+ 1 = Drop-down list / Picker.
+ A drop down list. Same as radio buttons, but can contain more items.

+ 2 = Slider.
+ Slider UI view with predefined stops as an options.

+ 3 = Modal Bottom Action Sheet.
+ Multiple-choice buttons that slide up from the bottom of the screen.

+ The answer is the ID of the response option.
4Multiple choice - Multiple selectA list of checkbox options. Requires the "responses" array to list the possible responses. + Users can select multiple responses. Available for anonymous aggregated public reporting.

+ The answer is a bitmask of selected choices.
6Day of the weekDay of the week input. + The UI can optimize itself for selecting days of the week [Sun][XXX][Tue][Wed][Thu][XXX][Sat].

+ 0 = Select multiple days simultaneously.
+ 1 = Pick a single day only.

+ The answer is a bitmasked value, days can be logically-OR'd together to specify multiple days of the week, ranging from SUN=0x1 to SAT=0x40.
7Slider0 = Integer select - default.
+ Slider, with a defined minimum and maximum.
+ By default, minimum = 0 and maximum = 100.
+ 1 = Floating point select.
+ 2 = Minutes:Seconds.

+ Answer is the number selected. For time, the answer is in integer seconds.
8Time in seconds since midnight0 = hours:minutes:seconds (am|pm) - default.
+ This accesses the native UI method of declaring a time.
+ 1 = hours:minutes (am|pm).

+ The answer is in integer seconds since midnight.
9Date and Time in ISO 86010 = Date and time.
+ 1 = Date only.

+ The answer is in ISO 8601 format, `YYYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm]`
10Text boxOpen-ended question.
+ For example, if you were to ask, "Who just walked by the camera?"

+ The answer is a string of text.
- /cloud/json/userProperties: - get: - summary: Get User Properties - operationId: Get User Properties - description: |- - This API returns user-specific property values. + ### Response Options - When using the returned content in your code, be sure to check for edge cases where no content was retrieved, - or the value is out-of-bounds, or the value was not the right type of information your code expects. + | Name | Type | Description | + | ---- | :--: | ----------- | + | id | integer | ID number for types of questions that feature a list of options | + | text | string | String for an option on a type of question that features a list of options | + + Retrieve requested questions. - You may also supply only a prefix of the property name you are looking for. - The Care Daily AI Platform will return all properties that contain the given property name prefix. + For an individual user, there should be at most one unanswered question available per day, unless the question is urgent. tags: - - System and User Properties + - Questions security: - userApiKey: [] parameters: - - name: name + - name: locationId in: query - description: Property name or optional name prefix to filter properties. Multiple values are supported. + description: Location ID to get questions + required: true + schema: + type: integer + - name: answerStatus + in: query + description: >- + Return questions with requested answer statuses. + By default questions with statuses 2 and 3 are returned. + Multiple values are supported. + schema: + type: integer + - name: editable + in: query + description: |- + Filter answered questions: +
true - return only editable answered questions, +
false - return only not editable answered questions, +
otherwise return all answered questions. + schema: + type: boolean + - name: collectionName + in: query + description: Questions collection name filter schema: type: string - - name: userId + - name: questionId in: query - description: User ID, used by an account with administrative privileges to retrieve the properties of another user + description: Extract a specific question ID. + schema: + type: integer + - name: appInstanceId + in: query + description: Only retrieve questions for a specific bot. + schema: + type: integer + - name: lang + in: query + description: Questions text language. If not set, user's or default language will be used. + schema: + type: string + - name: limit + in: query + description: Maximum number of questions to return. The default is unlimited. schema: type: integer responses: '200': - description: User Properties + description: Questions content: application/json: schema: @@ -11671,75 +10965,216 @@ paths: properties: resultCode: type: integer - properties: + questions: type: array items: type: object properties: - name: + id: + type: integer + appInstanceId: + type: integer + creationDate: type: string - value: + creationDateMs: + type: integer + key: + type: string + editable: + type: boolean + question: + type: string + placeholder: + type: string + collection: + type: object + properties: + name: + type: string + mlName: + type: object + additionalProperties: + type: string + description: Multilingual string map + description: + type: string + mlDescription: + type: object + additionalProperties: + type: string + description: Multilingual string map + icon: + type: string + iconFont: + type: string + media: + type: string + mediaContentType: + type: string + weight: + type: integer + deviceId: + type: string + icon: type: string displayType: type: integer - required: - - name - - value + defaultAnswer: + type: string + answerFormat: + type: string + slider: + type: object + properties: + min: + type: integer + max: + type: integer + inc: + type: integer + minDesc: + type: string + maxDesc: + type: string + unitsDesc: + type: string + sectionTitle: + type: string + sectionId: + type: integer + questionWeight: + type: integer + responseType: + type: integer + responseOptions: + type: array + items: + type: object + properties: + id: + type: integer + text: + type: string + required: + - id + - text + answerStatus: + type: integer + answer: + type: string + answerDate: + type: string + answerDateMs: + type: integer + answerModified: + type: boolean example: resultCode: 0 - properties: - - name: question.roommates - value: '1' - displayType: 2 - - name: question.xbox - value: 'false' + questions: + - id: 50234 + appInstanceId: 67 + creationDate: '2016-03-04T12:12:12-07:00' + creationDateMs: 1446537712000 + key: Question key + editable: true + question: What do you think of this question? + placeholder: Some hint + collection: + name: Urgent questions + mlName: + en: Urgent questions + description: Some description + mlDescription: + en: Collection description + icon: Icon name + iconFont: Icon font + media: Reference to media + mediaContentType: image/jpeg + weight: 10 + deviceId: optional_device_id + icon: optional_icon_name + displayType: 0 + defaultAnswer: '1000' + answerFormat: ^\d{4}$ + slider: + min: 0 + max: 100 + inc: 5 + minDesc: min value description + maxDesc: max value description + unitsDesc: UOM description + sectionTitle: Main questions + sectionId: 2 + questionWeight: 3 + responseType: 4 + responseOptions: + - id: 0 + text: Red + - id: 1 + text: Yellow + answerStatus: 4 + answer: This is some text input + answerDate: '2016-03-04T12:12:12-07:00' + answerDateMs: 1446539712000 + answerModified: false - post: - summary: Update User Properties - operationId: Update User Properties - description: >- - The application may update several user properties simultaneously. - The maximum value size may be 10,000 characters using this API. + put: + summary: Answer Bot Questions + operationId: Answer Bot Questions + description: |- + After answering a question, if the question is aggregated publicly then the user should also see how other people voted. + + A user can skip the question or prefer to not answer it by setting the corresponding answer status. + + Providing just the question ID the UI app can mark the question as notified. + + Only editable questions can be updated later. + Typically editable questions are used to configure Composer Apps and add further context to the user's data later. + + The user's tagged attributes should migrate with the question, such that when a new answer is selected, + any previous tags are removed and new tags are applied. + + The body and response is designed to handle answers to multiple questions simultaneously. tags: - - System and User Properties + - Questions security: - userApiKey: [] parameters: - - name: userId + - name: locationId in: query - description: User ID, used by an account with administrative privileges to update the properties for another user + description: Location ID to answer questions + required: true schema: type: integer requestBody: content: application/json: example: - property: - - name: question.roommates - value: '1' - displayType: 2 - - name: products.xbox - value: 'false' + questions: + - id: 50234 + answer: true + - id: 56236 + answerStatus: 3 + - id: 56237 schema: type: object properties: - property: + questions: type: array items: type: object properties: - name: - type: string - value: + id: + type: integer + answer: type: string - displayType: + answerStatus: type: integer required: - - name - - content + - id responses: '200': - description: OK + description: Answered questions content: application/json: schema: @@ -11747,96 +11182,102 @@ paths: properties: resultCode: type: integer + questions: + type: array + items: + type: object + properties: + id: + type: integer + answerStatus: + type: integer + answer: + type: string + answerDate: + type: string + answerDateMs: + type: integer + answerModified: + type: boolean + required: + - id + - answerStatus + - answerDate + - answerDateMs + - answerModified + - answer example: resultCode: 0 + questions: + - id: 50234 + answerStatus: 4 + answer: 'true' + answerDate: '2016-03-04T12:12:12-07:00' + answerDateMs: 1446539712000 + answerModified: false + - id: 56234 + answerStatus: 3 + answerDate: '2016-03-04T12:12:12-07:00' + answerDateMs: 1446539712000 + answerModified: true + - id: 56237 + answerStatus: 4 + answer: default answer + answerDate: '2016-03-04T12:12:12-07:00' + answerDateMs: 1446539712000 + answerModified: false - /cloud/json/userProperty/{name}: + /cloud/json/surveyAnswers: get: - summary: Get User Property - operationId: Get User Property + summary: Get Survey Answers + operationId: Get Survey Answers description: |- - This API will first attempt to return a user-specific property value in plain text. - If there is no user-specific property set, it will attempt to return a system-wide property value as plain text. - If there is no system property available, it will return no content. - - When using the returned content in your code, be sure to check for edge cases where no content was retrieved, - or the value is out-of-bounds, or the value was not the right type of information your code expects. - - When retrieving a system property, the API key is optional. - When the API key is not presented, the API will always return a System Property and never override it with a User Property of the same name. - - This is JSON format version of the previously documented API. + Returns history of survey answers. tags: - - System and User Properties + - Questions security: - userApiKey: [] + - botApiKey: [] parameters: - - name: name - in: path - description: Name of the property value to retrieve, i.e. "ppc.api.debug_level" + - name: locationId + in: query + description: Location ID required: true schema: - type: string + type: integer - name: userId in: query - description: User ID, used by an account with administrative privileges to retrieve the properties of another user + description: User ID filter schema: type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - value: - type: string - example: | - { - "resultCode": 0, - "value": "1" - } - - put: - summary: Update a User Property - operationId: Update a User Property - description: |- - The application may update a single user property with a very simple API requiring no JSON body. - The maximum value size may be 250 characters using this API. - tags: - - System and User Properties - security: - - userApiKey: [] - parameters: - - name: name - in: path - description: Name of the property to set a value for. Maximum of 250 characters. - required: true - schema: - type: string - - name: value + - name: surveyKey in: query - description: Value to set for this property. Maximum of 250 characters. - required: true + description: Survey filter schema: type: string - - name: displayType + - name: status in: query - description: Display type + description: |- + Survey answer status filter:
+ 0 - Open
+ 1 - Closed schema: type: integer - - name: userId + enum: [0,1] + - name: startDate in: query - description: User ID, used by an account with administrative privileges to update the properties for another user + description: Answers start date schema: - type: integer + type: string + - name: endDate + in: query + description: Answers end date + schema: + type: string responses: '200': - description: OK + description: Survey answers content: application/json: schema: @@ -11844,226 +11285,654 @@ paths: properties: resultCode: type: integer + answers: + type: array + description: Survey answer records + items: + type: object + properties: + answerId: + type: integer + description: Answer record ID + status: + type: integer + enum: [0,1] + description: |- + Answer record status:
+ 0 - open,
+ 1 - closed + userId: + type: integer + description: User ID + locationId: + type: integer + description: Location ID + startDate: + type: string + description: Answering start date + startDateMs: + type: string + description: Answering start time + notificationDate: + type: string + description: Last notificatyion send date + notificationDateMs: + type: string + description: Last notificatyion send time + endDate: + type: string + description: Answering end date + endDateMs: + type: string + description: Answering end time + survey: + type: object + properties: + surveyKey: + type: string + description: Unique Survey Key + organizationId: + type: integer + description: ID of organization, which is the owner of the survey + status: + type: integer + enum: [0,1,2] + description: |- + Survey status:
+ 0 - inactive,
+ 1 - active,
+ 2 - closed + title: + type: string + description: Title + description: + type: string + description: Description example: resultCode: 0 + answers: + - answerId: 12345 + status: 1 + userId: 678 + locationId: 456 + startDate: '2026-01-15T09:30:00-07:00' + startDateMs: '1736952600000' + notificationDate: '2026-01-15T09:30:00-07:00' + notificationDateMs: '1736952600000' + endDate: '2026-01-15T10:15:00-07:00' + endDateMs: '1736955300000' + survey: + surveyKey: 'monthly_wellness_check' + organizationId: 100 + status: 1 + title: 'Monthly Wellness Check' + description: 'Regular wellness assessment survey' + - answerId: 12346 + status: 0 + userId: 679 + locationId: 456 + startDate: '2026-01-20T14:00:00-07:00' + startDateMs: '1737406800000' + survey: + surveyKey: 'intake_assessment' + organizationId: 100 + status: 1 + title: 'Patient Intake Assessment' + description: 'Initial patient evaluation survey' - - /cloud/json/files: post: - summary: Upload New Device File - operationId: Upload Device File + summary: Start Answering Survey + operationId: Start Answering Survey description: |- - The "Content-Type" header must be like `video/*`, `image/*`, `audio/*`, `text/plain` or `application/octet-stream` - (see https://en.wikipedia.org/wiki/Internet_media_type for possible exact values). - For example: `video/mp4`, `image/jpeg`, `audio/mp3`. - The content type of thumbnail image is always `image/jpeg`. - - The `PPCAuthorization` headers may take on one form to identify the source device: - - * Using a Device Authentication Token: `PPCAuthorization: esp token="ABC12345"` - - A client can request only a creation of the file record without immediate uploading of the file or thumbnail content. - In this case the API will return temporary content and thumbnail upload URL's, where data can be uploaded, - and upload request headers, which must be used in each upload. - After finishing data upload the client must update the file as completed. - This method can improve large files upload speed. - - A client should provide the file creation timestamp. + Intitiates a survey answering. This API creates a new survey answer record for the requested user or returns an existing answer record. + + A user or a bot can submit answers to some survey questions in this request. Also question answers can be copied from a previously submitted survey by ID. + + The API can send an email to a user or to an organization notification users with a link to answer the survey or to view the existing answers, + if the `sendToUser` or the `botNotificationId` or the `notificationCategory` parameters are provided. + + The API returns the answer record with an authentication token and a URL to answer the survey for the user or view the previous answers. tags: - - Device Files + - Questions + security: + - userApiKey: [] + - botApiKey: [] parameters: - - name: proxyId + - name: locationId in: query - description: Device ID of the proxy that this file is being uploaded through + description: Answer a survey for this location required: true - schema: - type: string - - name: deviceId - in: query - description: Device ID of the device that generated this file, if different from the proxyId - schema: - type: string - - name: ext - in: query - description: File extension (For example, `mp4` or `png`) - schema: - type: string - - name: expectedSize - in: query - description: Expected total size in bytes, if available schema: type: integer - - name: timestamp - in: query - description: File creation time on the device in milliseconds - schema: - type: string - - name: timesec + - name: surveyKey in: query - description: File creation time on the device in seconds + description: Key of the survey to answer + required: true schema: type: string - - name: duration + - name: userId in: query - description: Duration of the video in seconds, for reporting to the UI + description: Answer a survey for this user + required: true schema: type: integer - - name: rotate + - name: answerId in: query - description: Rotation in degrees. The UI is expected to manually rotate the video back to being upright if this is set. + description: An existing answer record ID to recreate previous API response and action schema: type: integer - - name: fileId + - name: preAnswerId in: query - description: Existing file ID to replace the content and properties + description: Copy question answers from this answer record schema: type: integer - - name: thumbnail - in: query - description: true - the content is a thumbnail image and the file content will be uploaded later - schema: - type: boolean - - name: incomplete + - name: sendToUser in: query - description: >- - true - This file content will be added or replaced or extended later -
false - This file is complete + description: Send the email directly to the user schema: type: boolean - - name: uploadUrl + - name: botNotificationId in: query - description: true - Generate upload URL's for file's content and thumbnail, if the thumbnail parameter is true. + description: Send the email to organization notification users selected by this notification ID schema: - type: boolean - - name: type + type: integer + - name: notificationCategory in: query - description: >- - File type. By default it is defined from the content type. - However, this parameter is useful, if a thumbnail with different content type is uploaded first. + description: Send the email to organization notification users with this category schema: type: integer - - name: PPCAuthorization - in: header - description: Device's authorization - example: esp token=ABC12345 - schema: - type: string + requestBody: + content: + application/json: + example: + questions: + - questionKey: Question#1 + answer: '1' + - questionKey: Question#2 + answer: '0' + notificationModel: + connectionDate: 2026-02-02 + schema: + type: object + properties: + questions: + type: array + description: Optional answers to the survey questions + items: + type: object + properties: + questionKey: + type: string + description: Question key + answer: + type: string + description: Question answer + required: + - questionKey + - answer + notificationModel: + type: object + additionalProperties: + type: string + description: Additional notification template parameters as a string map responses: '200': - description: OK + description: Survey Answer content: application/json: schema: type: object properties: - status: - type: string - description: Device response status - fileRef: - type: integer - description: The File ID to reference this file later - filesAction: - type: integer - enum: [1,2] - description: >- - Actions performed by the API as a result of this file upload: -
1 - Old files have been deleted to make room for this one -
2 - There isn't enough space to upload this file - thumbnail: - type: boolean - description: true - the content is a thumbnail image - totalFilesSpace: - type: integer - description: The total space in the user's account for files in bytes. - usedFilesSpace: + resultCode: type: integer - description: The space in the user's account that has already been consumed in bytes. - fragments: + answer: + description: Survey answer record + type: object + properties: + answerId: + type: integer + description: Answer record ID + status: + type: integer + enum: [0,1] + description: |- + Answer record status:
+ 0 - open,
+ 1 - closed + userId: + type: integer + description: User ID + locationId: + type: integer + description: Location ID + startDate: + type: string + description: Answering start date + startDateMs: + type: string + description: Answering start time + notificationDate: + type: string + description: Last notificatyion send date + notificationDateMs: + type: string + description: Last notificatyion send time + endDate: + type: string + description: Answering end date + endDateMs: + type: string + description: Answering end time + token: + type: string + description: Answer the survey authentication token + surveyUrl: + type: string + description: Answer the survey URL + example: + resultCode: 0 + answer: + answerId: 12345 + status: 1 + userId: 678 + locationId: 456 + startDate: '2026-01-15T09:30:00-07:00' + startDateMs: '1736952600000' + notificationDate: '2026-01-15T09:30:00-07:00' + notificationDateMs: '1736952600000' + endDate: '2026-01-15T10:15:00-07:00' + endDateMs: '1736955300000' + token: abc.def.ghijklm + surveyUrl: https://app.caredaily.ai/espapi/redirect/survey/abc.def.ghijklm + + + /cloud/json/surveyQuestions: + get: + summary: Get Survey Questions + operationId: Get Survey Questions + description: |- + Return open organization survey details, sections, questions, and previously submitted answers. + + The request can be authenticated either by a survey answer token (Bearer JWT) or by a user or bot API key. + tags: + - Questions + security: + - surveyAnswerAuth: [] + - userApiKey: [] + - botApiKey: [] + parameters: + - name: locationId + in: query + description: Location ID when a user or a bot is authenticated + schema: + type: integer + - name: answerId + in: query + description: Answer ID when a user or a bot is authenticated + schema: + type: integer + responses: + '200': + description: Survey Questions + content: + application/json: + schema: + type: object + properties: + resultCode: type: integer - description: The total fragments that compose this file. Always 1 for this API. - contentUrl: - type: string - description: Temporary URL to upload the file content - thumbnailUrl: - type: string - description: Temporary URL to upload the thumbnail content - uploadHeaders: + survey: type: object - description: Headers required to upload the content to the URLs + properties: + surveyKey: + type: string + description: Survey Key + organizationId: + type: integer + description: ID of organization, which is the owner of the survey + status: + type: integer + enum: [0,1,2] + description: |- + Survey status:
+ 0 - inactive,
+ 1 - active,
+ 2 - closed + answerStatus: + type: integer + enum: [0,1] + description: |- + Survey answer status:
+ 0 - open to submit answers
+ 1 - closed + title: + type: string + description: Title + description: + type: string + description: Description + instructions: + type: string + description: Answer Instructions + pagination: + type: boolean + description: Pagination flag to display survey in UI by pages + startDate: + type: string + description: Answering process start date + startDateMs: + type: integer + description: Answering process start time + notificationDate: + type: string + description: The last notification send date + notificationDateMs: + type: integer + description: The last notification send time + sections: + type: array + items: + type: object + properties: + sectionId: + type: integer + description: Section ID + orderNum: + type: integer + description: Ordering number within the survey or the parent section + title: + type: string + description: Optinal section title + description: + type: string + description: Section description + questions: + type: array + items: + type: object + properties: + questionKey: + type: string + description: Question key uniqie within the survey + orderNum: + type: integer + description: Ordering number within the the section + question: + type: string + description: Question text + description: + type: string + description: Question description + responseType: + type: integer + description: Answer type + optional: + type: boolean + description: If the answer is optional to submit the survey + displayType: + type: integer + description: UI display type for each type of answer (for example, yes/no vs. on/off switch, or a slider that shows integers vs. a slider that shows minutes:seconds) + answerFormat: + type: string + description: Regular expression to validate answer format in UI. + slider: + type: object + description: Slider + properties: + min: + type: integer + description: Answer minimum value + max: + type: integer + description: Answer maximum value + inc: + type: integer + description: Slider increment + minDesc: + type: string + description: Description of slider minimum value + maxDesc: + type: string + description: Description of slider maximum value + unitsDesc: + type: string + description: Unit description + responseOptions: + type: array + description: + items: + type: object + properties: + id: + type: integer + description: ID number for types of questions that feature a list of options + text: + type: string + description: Description of the option + required: + - id + - text + answer: + type: string + description: Previous answer value + answerDate: + type: string + description: Previous answer date + answerDateMs: + type: string + description: Previous answer time example: - status: ACK - fileRef: 12345 - filesAction: 1 - thumbnail: true - totalFilesSpace: 10000000 - usedFilesSpace: 1000000 - fragments: 3 - contentUrl: >- - https://s3.amazonaws.com/cbacket/fileId?X-Amz-Algorithm=AWS4-HMAC-SHA256... - thumbnailUrl: >- - https://s3.amazonaws.com/tbacket/fileId?X-Amz-Algorithm=AWS4-HMAC-SHA256... - uploadHeaders: - x-amz-server-side-encryption: AES256 + resultCode: 0 + survey: + surveyKey: ConnectionSurvey + organizationId: 100 + status: 1 + answerStatus: 0 + title: Connections Survey + description: Successful Aging Connections Questionnaire + instructions: Please answer all questions honestly + pagination: true + startDate: '2026-01-15T09:30:00-07:00' + startDateMs: 1736952600000 + notificationDate: '2026-01-15T09:30:00-07:00' + notificationDateMs: 1736952600000 + sections: + - sectionId: 1 + orderNum: 1 + title: Personal Information + questions: + - questionKey: age_range + orderNum: 1 + question: What is your age range? + description: Select the range that includes your current age + responseType: 4 + optional: false + displayType: 1 + responseOptions: + - id: 1 + text: 18-30 + - id: 2 + text: 31-50 + - id: 3 + text: 51-70 + - id: 4 + text: 71+ + - questionKey: living_alone + orderNum: 2 + question: Do you live alone? + responseType: 1 + optional: false + displayType: 1 + answer: 'true' + answerDate: '2026-01-15T10:00:00-07:00' + answerDateMs: '1736954400000' + - sectionId: 2 + orderNum: 2 + title: Health Assessment + questions: + - questionKey: pain_level + orderNum: 1 + question: Rate your current pain level + description: Use the slider to indicate your pain level + responseType: 2 + optional: false + displayType: 2 + slider: + min: 0 + max: 10 + inc: 1 + minDesc: No pain + maxDesc: Severe pain + unitsDesc: points + - questionKey: medication_notes + orderNum: 2 + question: Any notes about your medications? + responseType: 3 + optional: true + displayType: 1 + answerFormat: '^.{0,500}$' - get: - summary: Get Device Files - operationId: Get Device Files - description: Return a list of the user's files, and any files that have been shared with this user by other users. + put: + summary: Answer Survey Questions + operationId: Answer Survey Questions + description: |- + Put survey answers by a Survey API key to the latest open survey response. + A user can submit a portion of answers in one API call. Some of answers can overwrite previous. + + The API checks, if the survey is not answered yet by the user (withing configured date interval). + + An optional parameter `status` is used to finalize the latest survey response. + In this case the API checks that all questions answered and triggers bots. + + The request can be authenticated either by a survey answer token (Bearer JWT) or by a user or bot API key. tags: - - Device Files + - Questions security: + - surveyAnswerAuth: [] - userApiKey: [] + - botApiKey: [] parameters: - name: locationId in: query - description: Files location ID - required: true - schema: - type: integer - - name: type - in: query - description: Type of file to obtain in the list + description: Location ID when a user or a bot is authenticated schema: type: integer - - name: owners + - name: answerId in: query - description: >- - Filter files by owners bitmap: -
1 - only own files, default, -
2 - only shared files, -
3 - own and shared, -
4 - own deleted files + description: Answer ID when a user or a bot is authenticated schema: type: integer - enum: [1,2,3,4] - - name: ownerId + - name: status in: query - description: User ID to filter files by the specific owner + description: |- + Change survey response status: 1 - close schema: type: integer - - name: deviceId - in: query - description: Camera device ID to filter files by the specific camera - schema: - type: string - - name: deviceDescription - in: query - description: Camera device description to filter files by the specific camera + requestBody: + content: + application/json: + example: + questions: + - questionKey: Question#1 + answer: '1' + - questionKey: Question#2 + answer: '0' + schema: + type: object + properties: + questions: + type: array + items: + type: object + properties: + questionKey: + type: string + description: Question key + answer: + type: string + description: Question answer + required: + - questionKey + - answer + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + + /cloud/json/systemProperty/{propertyName}: + get: + summary: Get User or System Property + operationId: Get User or System Property + description: |- + This API will first attempt to return a user-specific property value in plain text. + If there is no user-specific property set, it will attempt to return a system-wide property value as plain text. + If there is no system property available, it will return no content. + + When using the returned content in your code, be sure to check for edge cases where no content was retrieved, + or the value is out-of-bounds, or the value was not the right type of information your code expects. + + When retrieving a system property, the API key is optional. + When the API key is not presented, the API will always return a System Property and never override it with a User Property of the same name. + tags: + - System and User Properties + security: + - userApiKey: [] + - botApiKey: [] + parameters: + - name: propertyName + in: path + description: Name of the property value to retrieve, i.e. "ppc.api.debug_level" + required: true schema: type: string - - name: startDate + responses: + '200': + description: Property value + content: + text/plain: + example: | + DEBUG + + + /cloud/json/userProperties: + get: + summary: Get User Properties + operationId: Get User Properties + description: |- + This API returns user-specific property values. + + When using the returned content in your code, be sure to check for edge cases where no content was retrieved, + or the value is out-of-bounds, or the value was not the right type of information your code expects. + + You may also supply only a prefix of the property name you are looking for. + The Care Daily AI Platform will return all properties that contain the given property name prefix. + tags: + - System and User Properties + security: + - userApiKey: [] + parameters: + - name: name in: query - description: Optional start date to start the list of files + description: Property name or optional name prefix to filter properties. Multiple values are supported. schema: type: string - - name: endDate + - name: userId in: query - description: Optional end date to end the list of files + description: User ID, used by an account with administrative privileges to retrieve the properties of another user schema: - type: string + type: integer responses: '200': - description: Device Files + description: User Properties content: application/json: schema: @@ -12071,149 +11940,72 @@ paths: properties: resultCode: type: integer - totalFilesSpace: - type: integer - description: The total space in the user's account for files in bytes. - usedFilesSpace: - type: integer - description: The space in the user's account that has already been consumed in bytes. - tempKey: - type: string - description: Temporary API key, which can be used to download the files content and obtain files information. - tempKeyExpire: - type: string - description: Temporary API key expiry - tempKeyExpireMs: - type: integer - files: + properties: type: array items: type: object properties: - id: - type: integer - description: File ID - type: - type: integer - description: File Type name: type: string - description: Generated File Name - thumbnail: - type: boolean - description: If thumbnail is avaialble - viewed: - type: boolean - description: If the file marked as viewed - favourite: - type: boolean - description: If the file marked as favourite - viewCount: - type: integer - description: How many time the file been viewed - publicAccess: - type: boolean - description: If it is publicly acessible (without login) - creationDate: - type: string - description: The creation date - creationTime: - type: integer - description: The creation date in milliseconds - size: - type: integer - description: Size of the file in bytes - duration: - type: integer - description: Duration of the video or audio file, in seconds - rotate: - type: integer - description: Degrees this video has been rotated. It is up to the playback mechanism to rotate the video upright again, if necessary. - incomplete: - type: boolean - description: If the file's upload is not completed yet - device: - type: object - description: Assosiated device instance - properties: - id: - type: string - type: - type: integer - desc: - type: string - required: - - id - - type - - name - - thumbnail - - viewed - - favourite - - viewCount - - publicAccess - - creationDate - - creationTime - - size - - incomplete - - device - example: - resultCode: 0 - totalFilesSpace: 10485760 - usedFilesSpace: 1043858 - tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ - tempKeyExpire: '2013-07-01T14:54:54-04:00' - files: - - id: 123 - type: 1 - name: 123.mp4 - thumbnail: false - viewed: true - favourite: false - viewCount: 1 - publicAccess: false - creationDate: '2013-06-05T16:43:59-07:00' - creationTime: 1370475839000 - size: 3479190 - duration: 60 - rotate: 180 - incomplete: false - device: - id: ABC123 - type: 21 - desc: Living room camera - - id: 124 - type: 2 - name: 124.jpg - thumbnail: true - viewed: false - favourite: false - viewCount: 2 - publicAccess: false - creationDate: '2013-06-05T16:43:59-07:00' - creationTime: 1370475839000 - size: 347919 - rotate: 0 - incomplete: true - device: - id: ABC124 - type: 21 - desc: Door camera + value: + type: string + displayType: + type: integer + required: + - name + - value + example: + resultCode: 0 + properties: + - name: question.roommates + value: '1' + displayType: 2 + - name: question.xbox + value: 'false' - delete: - summary: Delete All Device Files - operationId: Delete All Device Files - description: This action will delete all files on the location that are not marked as favorite. + post: + summary: Update User Properties + operationId: Update User Properties + description: >- + The application may update several user properties simultaneously. + The maximum value size may be 10,000 characters using this API. tags: - - Device Files + - System and User Properties security: - userApiKey: [] parameters: - - name: locationId + - name: userId in: query - description: Files location ID - required: true + description: User ID, used by an account with administrative privileges to update the properties for another user schema: type: integer + requestBody: + content: + application/json: + example: + property: + - name: question.roommates + value: '1' + displayType: 2 + - name: products.xbox + value: 'false' + schema: + type: object + properties: + property: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + displayType: + type: integer + required: + - name + - content responses: '200': description: OK @@ -12228,56 +12020,41 @@ paths: resultCode: 0 - /cloud/json/filesByCount/{count}: + /cloud/json/userProperty/{name}: get: - summary: Get Last Device Files - operationId: Get Last Device Files - description: Return a list of last N the user's files before specific date. + summary: Get User Property + operationId: Get User Property + description: |- + This API will first attempt to return a user-specific property value in plain text. + If there is no user-specific property set, it will attempt to return a system-wide property value as plain text. + If there is no system property available, it will return no content. + + When using the returned content in your code, be sure to check for edge cases where no content was retrieved, + or the value is out-of-bounds, or the value was not the right type of information your code expects. + + When retrieving a system property, the API key is optional. + When the API key is not presented, the API will always return a System Property and never override it with a User Property of the same name. + + This is JSON format version of the previously documented API. tags: - - Device Files + - System and User Properties security: - userApiKey: [] parameters: - - name: count + - name: name in: path - description: Maximum number of files to return - required: true - schema: - type: integer - - name: locationId - in: query - description: Files location ID + description: Name of the property value to retrieve, i.e. "ppc.api.debug_level" required: true - schema: - type: integer - - name: startDate - in: query - description: Optional start date to start the list of files. - schema: - type: string - - name: endDate - in: query - description: Optional end date to end the list of files, default is the current date. schema: type: string - - name: type + - name: userId in: query - description: Type of file to obtain in the list + description: User ID, used by an account with administrative privileges to retrieve the properties of another user schema: type: integer - - name: deviceId - in: query - description: Camera device ID to filter files by the specific camera - schema: - type: string - - name: deviceDescription - in: query - description: Camera device description to filter files by the specific camera - schema: - type: string responses: '200': - description: Device Files + description: OK content: application/json: schema: @@ -12285,179 +12062,47 @@ paths: properties: resultCode: type: integer - totalFilesSpace: - type: integer - description: The total space in the user's account for files in bytes. - tempKey: - type: string - description: Temporary API key, which can be used to download the files content and obtain files information. - tempKeyExpire: + value: type: string - description: Temporary API key expiry - tempKeyExpireMs: - type: integer - files: - type: array - items: - type: object - properties: - id: - type: integer - description: File ID - type: - type: integer - description: File Type - name: - type: string - description: Generated File Name - thumbnail: - type: boolean - description: If thumbnail is avaialble - viewed: - type: boolean - description: If the file marked as viewed - favourite: - type: boolean - description: If the file marked as favourite - viewCount: - type: integer - description: How many time the file been viewed - publicAccess: - type: boolean - description: If it is publicly acessible (without login) - creationDate: - type: string - description: The creation date - creationTime: - type: integer - description: The creation date in milliseconds - size: - type: integer - description: Size of the file in bytes - duration: - type: integer - description: Duration of the video or audio file, in seconds - rotate: - type: integer - description: Degrees this video has been rotated. It is up to the playback mechanism to rotate the video upright again, if necessary. - incomplete: - type: boolean - description: If the file's upload is not completed yet - device: - type: object - description: Assosiated device instance - properties: - id: - type: string - type: - type: integer - desc: - type: string - required: - - id - - type - - name - - thumbnail - - viewed - - favourite - - viewCount - - publicAccess - - creationDate - - creationTime - - size - - incomplete - - device - example: - resultCode: 0 - tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ - tempKeyExpire: '2013-07-01T14:54:54-04:00' - totalFilesSpace: 10485760 - files: - - id: 123 - type: 1 - name: 123.mp4 - thumbnail: false - viewed: true - favourite: false - viewCount: 1 - publicAccess: false - creationDate: '2013-06-05T16:43:59-07:00' - creationTime: 1370475839000 - size: 3479190 - duration: 60 - rotate: 180 - incomplete: false - device: - id: ABC123 - type: 21 - desc: Living room camera - - id: 124 - type: 2 - name: 124.jpg - thumbnail: true - viewed: false - favourite: false - viewCount: 2 - publicAccess: false - creationDate: '2013-06-05T16:43:59-07:00' - creationTime: 1370475839000 - size: 347919 - rotate: 0 - incomplete: true - device: - id: ABC124 - type: 21 - desc: Door camera - + example: | + { + "resultCode": 0, + "value": "1" + } - /cloud/json/files/{fileId}: - post: - summary: Upload Device File Fragment - operationId: Upload Device File Fragment + put: + summary: Update a User Property + operationId: Update a User Property description: |- - Allow to add a fragment to the content of the existing file or upload a thumbnail. - - `Content-Type` and `PPCAuthorization` must set the same way as in uploading a new file. + The application may update a single user property with a very simple API requiring no JSON body. + The maximum value size may be 250 characters using this API. tags: - - Device Files + - System and User Properties + security: + - userApiKey: [] parameters: - - name: fileId + - name: name in: path - description: Existing file ID + description: Name of the property to set a value for. Maximum of 250 characters. required: true schema: - type: integer - - name: proxyId + type: string + - name: value in: query - description: Device ID of the proxy that this file is being uploaded through + description: Value to set for this property. Maximum of 250 characters. required: true schema: type: string - - name: thumbnail - in: query - description: true - the content is a thumbnail image - schema: - type: boolean - - name: incomplete + - name: displayType in: query - description: >- - true - The file will be extended later -
false - This file is complete + description: Display type schema: - type: boolean - - name: index + type: integer + - name: userId in: query - description: >- - Fragment index starting from 0 to identify unique file fragment. - It is used for additional control over uploaded data. + description: User ID, used by an account with administrative privileges to update the properties for another user schema: type: integer - - name: PPCAuthorization - in: header - description: Device's authorization - example: esp token=ABC12345 - schema: - type: string responses: '200': description: OK @@ -12466,220 +12111,112 @@ paths: schema: type: object properties: - status: - type: string - description: Device response status - filesAction: - type: integer - enum: [1,2] - description: >- - Actions performed by the API as a result of this file upload: -
1 - Old files have been deleted to make room for this one -
2 - There isn't enough space to upload this file - totalFilesSpace: - type: integer - description: The total space in the user's account for files in bytes. - usedFilesSpace: - type: integer - description: The space in the user's account that has already been consumed in bytes. - fragments: + resultCode: type: integer - description: The total fragments that compose this file. example: - status: ACK - filesAction: 1 - thumbnail: true - totalFilesSpace: 10000000 - usedFilesSpace: 1000000 - fragments: 3 + resultCode: 0 - get: - summary: Download Device File - operationId: Download Device File + + /cloud/json/files: + post: + summary: Upload New Device File + operationId: Upload Device File description: |- - The `Range` HTTP Header is optional, and will only return a chunk of the total content. - If used, it is recommended to select a range that is a multiple of 10240 bytes. + The "Content-Type" header must be like `video/*`, `image/*`, `audio/*`, `text/plain` or `application/octet-stream` + (see https://en.wikipedia.org/wiki/Internet_media_type for possible exact values). + For example: `video/mp4`, `image/jpeg`, `audio/mp3`. + The content type of thumbnail image is always `image/jpeg`. - See https://www.rfc-editor.org/rfc/rfc9110.html#name-accept-ranges for a discussion on the header options. + The `PPCAuthorization` headers may take on one form to identify the source device: - A temporary API key provided in the query parameter may be used to forward a link to other part of the app. - A temporary API key can be obtained by calling the loginByKey API. - It is expired soon after receiving. + * Using a Device Authentication Token: `PPCAuthorization: esp token="ABC12345"` + + A client can request only a creation of the file record without immediate uploading of the file or thumbnail content. + In this case the API will return temporary content and thumbnail upload URL's, where data can be uploaded, + and upload request headers, which must be used in each upload. + After finishing data upload the client must update the file as completed. + This method can improve large files upload speed. + + A client should provide the file creation timestamp. tags: - Device Files - security: - - userApiKey: [] - - tempApiKey: [] - - botApiKey: [] parameters: - - name: fileId - in: path - description: File ID to download + - name: proxyId + in: query + description: Device ID of the proxy that this file is being uploaded through required: true + schema: + type: string + - name: deviceId + in: query + description: Device ID of the device that generated this file, if different from the proxyId + schema: + type: string + - name: ext + in: query + description: File extension (For example, `mp4` or `png`) + schema: + type: string + - name: expectedSize + in: query + description: Expected total size in bytes, if available schema: type: integer - - name: thumbnail + - name: timestamp in: query - description: >- - true - Download the thumbnail for this file -
false - Download the actual file, not the thumbnail, default + description: File creation time on the device in milliseconds schema: - type: boolean - - name: Range - in: header - description: Data range - example: bytes=10240-20479 + type: string + - name: timesec + in: query + description: File creation time on the device in seconds schema: type: string - responses: - '200': - description: OK. The file content is returned in full. - headers: - Accept-Ranges: - schema: - type: string - description: Accepted content range values in bytes - Content-Type: - schema: - type: string - description: The file's content type - Content-Length: - schema: - type: integer - Last-Modified: - schema: - type: string - description: The file's creation date - Content-Range: - schema: - type: string - description: >- - If the `Range` of the content was requested. - This will be in the format of `bytes {start}-{end}/{total size}`. - For example: `Content-Range: bytes 21010-47021/47022`. - Content-Disposition: - schema: - type: string - description: The filename when the whole file is requested. - ETag: - schema: - type: string - description: The file's ID - '204': - description: No Content. The file exist, but the content is not available for this request. - '206': - description: Partial Content. The file content is partially returned. - headers: - Accept-Ranges: - schema: - type: string - description: Accepted content range values in bytes - Content-Type: - schema: - type: string - description: The file's content type - Content-Length: - schema: - type: integer - Last-Modified: - schema: - type: string - description: The file's creation date - Content-Range: - schema: - type: string - description: >- - If the `Range` of the content was requested. -
This will be in the format of `bytes {start}-{end}/{total size}`. -
For example: `Content-Range: bytes 21010-47021/47022`. - Content-Disposition: - schema: - type: string - description: The filename when the whole file is requested. - ETag: - schema: - type: string - description: The file's ID - '401': - description: Unauthorized. The API key is wrong. - '404': - description: Not Found. The file does not exist. - '500': - description: Internal error. Something went wrong on our side. - - put: - summary: Update Device File Attributes - operationId: Update Device File Attributes - description: |- - Update the file's attributes to declare, if the file has been viewed or not, - if it's a favourite file and shouldn't be auto-deleted, and whether the file is available for public access. - - The file publisher (camera) can update it as completed. - - Also, this API can be used to recover deleted files. - tags: - - Device Files - security: - - userApiKey: [] - parameters: - - name: fileId - in: path - description: File ID to update - required: true + - name: duration + in: query + description: Duration of the video in seconds, for reporting to the UI schema: type: integer - - name: locationId + - name: rotate in: query - description: File location ID - required: true + description: Rotation in degrees. The UI is expected to manually rotate the video back to being upright if this is set. schema: type: integer - - name: proxyId + - name: fileId in: query - description: Device ID of the proxy that this file is being uploaded through + description: Existing file ID to replace the content and properties schema: - type: string - - name: incomplete + type: integer + - name: thumbnail in: query - description: Set it to false for updating the file as completed + description: true - the content is a thumbnail image and the file content will be uploaded later schema: type: boolean - - name: recover + - name: incomplete in: query - description: Set it to true to recover a deleted file + description: >- + true - This file content will be added or replaced or extended later +
false - This file is complete schema: type: boolean - - name: pure + - name: uploadUrl in: query - description: true - the server will not make any modification of the file content + description: true - Generate upload URL's for file's content and thumbnail, if the thumbnail parameter is true. schema: type: boolean + - name: type + in: query + description: >- + File type. By default it is defined from the content type. + However, this parameter is useful, if a thumbnail with different content type is uploaded first. + schema: + type: integer - name: PPCAuthorization in: header - description: Device's authorization (required for updating file as completed) + description: Device's authorization example: esp token=ABC12345 schema: type: string - requestBody: - content: - application/json: - example: - file: - viewed: true - favourite: true - publicAccess: true - schema: - type: object - properties: - file: - type: object - properties: - viewed: - type: boolean - favourite: - type: boolean - publicAccess: - type: boolean responses: '200': description: OK @@ -12688,34 +12225,114 @@ paths: schema: type: object properties: - resultCode: + status: + type: string + description: Device response status + fileRef: + type: integer + description: The File ID to reference this file later + filesAction: + type: integer + enum: [1,2] + description: >- + Actions performed by the API as a result of this file upload: +
1 - Old files have been deleted to make room for this one +
2 - There isn't enough space to upload this file + thumbnail: + type: boolean + description: true - the content is a thumbnail image + totalFilesSpace: + type: integer + description: The total space in the user's account for files in bytes. + usedFilesSpace: + type: integer + description: The space in the user's account that has already been consumed in bytes. + fragments: type: integer + description: The total fragments that compose this file. Always 1 for this API. + contentUrl: + type: string + description: Temporary URL to upload the file content + thumbnailUrl: + type: string + description: Temporary URL to upload the thumbnail content + uploadHeaders: + type: object + description: Headers required to upload the content to the URLs example: - resultCode: 0 + status: ACK + fileRef: 12345 + filesAction: 1 + thumbnail: true + totalFilesSpace: 10000000 + usedFilesSpace: 1000000 + fragments: 3 + contentUrl: >- + https://s3.amazonaws.com/cbacket/fileId?X-Amz-Algorithm=AWS4-HMAC-SHA256... + thumbnailUrl: >- + https://s3.amazonaws.com/tbacket/fileId?X-Amz-Algorithm=AWS4-HMAC-SHA256... + uploadHeaders: + x-amz-server-side-encryption: AES256 - delete: - summary: Delete Device File - operationId: Delete Device File + get: + summary: Get Device Files + operationId: Get Device Files + description: Return a list of the user's files, and any files that have been shared with this user by other users. tags: - Device Files security: - userApiKey: [] parameters: - - name: fileId - in: path - description: File ID to delete + - name: locationId + in: query + description: Files location ID required: true schema: type: integer - - name: locationId + - name: type in: query - description: File location ID - required: true + description: Type of file to obtain in the list + schema: + type: integer + - name: owners + in: query + description: >- + Filter files by owners bitmap: +
1 - only own files, default, +
2 - only shared files, +
3 - own and shared, +
4 - own deleted files + schema: + type: integer + enum: [1,2,3,4] + - name: ownerId + in: query + description: User ID to filter files by the specific owner schema: type: integer + - name: deviceId + in: query + description: Camera device ID to filter files by the specific camera + schema: + type: string + - name: deviceDescription + in: query + description: Camera device description to filter files by the specific camera + schema: + type: string + - name: startDate + in: query + description: Optional start date to start the list of files + schema: + type: string + - name: endDate + in: query + description: Optional end date to end the list of files + schema: + type: string responses: '200': - description: OK + description: Device Files content: application/json: schema: @@ -12723,52 +12340,152 @@ paths: properties: resultCode: type: integer + totalFilesSpace: + type: integer + description: The total space in the user's account for files in bytes. + usedFilesSpace: + type: integer + description: The space in the user's account that has already been consumed in bytes. + tempKey: + type: string + description: Temporary API key, which can be used to download the files content and obtain files information. + tempKeyExpire: + type: string + description: Temporary API key expiry + tempKeyExpireMs: + type: integer + files: + type: array + items: + type: object + properties: + id: + type: integer + description: File ID + type: + type: integer + description: File Type + name: + type: string + description: Generated File Name + thumbnail: + type: boolean + description: If thumbnail is avaialble + viewed: + type: boolean + description: If the file marked as viewed + favourite: + type: boolean + description: If the file marked as favourite + viewCount: + type: integer + description: How many time the file been viewed + publicAccess: + type: boolean + description: If it is publicly acessible (without login) + creationDate: + type: string + description: The creation date + creationTime: + type: integer + description: The creation date in milliseconds + size: + type: integer + description: Size of the file in bytes + duration: + type: integer + description: Duration of the video or audio file, in seconds + rotate: + type: integer + description: Degrees this video has been rotated. It is up to the playback mechanism to rotate the video upright again, if necessary. + incomplete: + type: boolean + description: If the file's upload is not completed yet + device: + type: object + description: Assosiated device instance + properties: + id: + type: string + type: + type: integer + desc: + type: string + required: + - id + - type + - name + - thumbnail + - viewed + - favourite + - viewCount + - publicAccess + - creationDate + - creationTime + - size + - incomplete + - device example: resultCode: 0 + totalFilesSpace: 10485760 + usedFilesSpace: 1043858 + tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ + tempKeyExpire: '2013-07-01T14:54:54-04:00' + files: + - id: 123 + type: 1 + name: 123.mp4 + thumbnail: false + viewed: true + favourite: false + viewCount: 1 + publicAccess: false + creationDate: '2013-06-05T16:43:59-07:00' + creationTime: 1370475839000 + size: 3479190 + duration: 60 + rotate: 180 + incomplete: false + device: + id: ABC123 + type: 21 + desc: Living room camera + - id: 124 + type: 2 + name: 124.jpg + thumbnail: true + viewed: false + favourite: false + viewCount: 2 + publicAccess: false + creationDate: '2013-06-05T16:43:59-07:00' + creationTime: 1370475839000 + size: 347919 + rotate: 0 + incomplete: true + device: + id: ABC124 + type: 21 + desc: Door camera - - /cloud/json/files/{fileId}/url: - get: - summary: Get Device File Download URL - operationId: Get Device File Download URL - description: >- - A client can request temporary download URL's to get file and thumbnail - content directly from S3 instead of copying it through the server. + delete: + summary: Delete All Device Files + operationId: Delete All Device Files + description: This action will delete all files on the location that are not marked as favorite. tags: - Device Files security: - userApiKey: [] parameters: - - name: fileId - in: path - description: File ID to download - required: true - schema: - type: integer - name: locationId in: query - description: File location ID + description: Files location ID required: true schema: type: integer - - name: content - in: query - description: Request file content URL - schema: - type: boolean - - name: thumbnail - in: query - description: Request thumbnail content URL - schema: - type: boolean - - name: expiration - in: query - description: URL's expiration in milliseconds since the current time - schema: - type: integer responses: '200': - description: File content and thumbnail URLs + description: OK content: application/json: schema: @@ -12776,99 +12493,60 @@ paths: properties: resultCode: type: integer - contentUrl: - type: string - thumbnailUrl: - type: string example: resultCode: 0 - contentUrl: >- - https://s3.amazonaws.com/bucket1/object1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180704T220443Z&X-Amz-SignedHeaders=host&X-Amz-Expires=10&X-Amz-Credential=AKIAJPAZD&X-Amz-Signature=af7329c26 - thumbnailUrl: >- - https://s3.amazonaws.com/bucket2/object1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180704T220443Z&X-Amz-SignedHeaders=host&X-Amz-Expires=10&X-Amz-Credential=AKIAJPAZD&X-Amz-Signature=af7329c26 - /cloud/json/filesSummary/{aggregation}: + /cloud/json/filesByCount/{count}: get: - summary: Get Summary of Device Files - operationId: Get Summary of Device Files - description: |- - Users can collect a massive list of files. Even the plain text to describe these files can sometimes be megabytes long. - This API helps describe what files exist on the server, so the user can drill into the data without downloading everything all at once. - - If is highly recommended to call this API first and then use received information to obtain files list for specific time period. - - In some cases even files summary data can be very long. - So it is recommended to use optional `startDate` and `endDate` parameters. - By default `endDate` is set to the creation time of the last uploaded user file. - If `startDate` is not provided, it will be estimated by the cloud according to the aggregation to provide better API performance. - - This API will return a summary of files grouped by files creation date in descending order by default, - providing summary information for the files within each aggregation period (day, week, month, etc.). - - For better API performance request only own user files information with aggregation by days without details and for limited time period. + summary: Get Last Device Files + operationId: Get Last Device Files + description: Return a list of last N the user's files before specific date. tags: - Device Files security: - userApiKey: [] parameters: - - name: aggregation + - name: count in: path - description: >- - The duration of time across which to aggregate summary information -
1 - hour -
2 - day -
3 - month -
4 - 7-day week from Sunday to Saturday + description: Maximum number of files to return required: true schema: type: integer - enum: [1,2,3,4] - name: locationId in: query description: Files location ID required: true schema: type: integer - - name: details + - name: startDate in: query - description: >- - If true, the API will return detailed information - slow. -
Otherwise only total number of files will be returned. + description: Optional start date to start the list of files. schema: - type: boolean - - name: timeZone + type: string + - name: endDate in: query - description: >- - Time zone ID to separate aggregated summary information. -
For example, `America/Los_Angeles`. + description: Optional end date to end the list of files, default is the current date. schema: type: string - name: type in: query - description: >- - Filter by type of file. -
0 - any file -
1 - videos only -
2 - images only -
3 - audio only -
4 - bitmaps only + description: Type of file to obtain in the list schema: type: integer - enum: [0,1,2,3,4] - - name: startDate + - name: deviceId in: query - description: Start date for which to begin returning aggregate summary information on the user's files + description: Camera device ID to filter files by the specific camera schema: type: string - - name: endDate + - name: deviceDescription in: query - description: End date for which to stop returning aggregate summary information on the user's files + description: Camera device description to filter files by the specific camera schema: type: string responses: '200': - description: Files summary + description: Device Files content: application/json: schema: @@ -12879,266 +12557,174 @@ paths: totalFilesSpace: type: integer description: The total space in the user's account for files in bytes. - usedFilesSpace: - type: integer - description: The space in the user's account that has already been consumed in bytes. - filesCount: - type: integer - description: Number of files - startDate: + tempKey: type: string - description: Date when first file uploaded - startDateMs: - type: integer - endDate: + description: Temporary API key, which can be used to download the files content and obtain files information. + tempKeyExpire: type: string - description: Date when last file uploaded - endDateMs: + description: Temporary API key expiry + tempKeyExpireMs: type: integer - summaries: + files: type: array - description: Information for the files within each aggregation period items: type: object properties: - date: - type: string - description: The beginning of an aggregation period - dateMs: + id: type: integer - total: + description: File ID + type: type: integer - description: Number of files - deleted: + description: File Type + name: + type: string + description: Generated File Name + thumbnail: + type: boolean + description: If thumbnail is avaialble + viewed: + type: boolean + description: If the file marked as viewed + favourite: + type: boolean + description: If the file marked as favourite + viewCount: type: integer - description: Number of deleted files + description: How many time the file been viewed + publicAccess: + type: boolean + description: If it is publicly acessible (without login) + creationDate: + type: string + description: The creation date + creationTime: + type: integer + description: The creation date in milliseconds size: type: integer - description: Total files size in bytes, if details requested + description: Size of the file in bytes duration: type: integer - description: Total files duration, if details requested - viewed: - type: integer - description: Number of viewed files, if details requested - favourite: + description: Duration of the video or audio file, in seconds + rotate: type: integer - description: Number of favourite files, if details requested - required: - - date - - dateMs - - total - - deleted - example: - resultCode: 0 - totalFilesSpace: 10485760 - usedFilesSpace: 1043858 - filesCount: 36 - startDate: '2014-02-01T00:00:00-08:00' - startDateMs: 1391241600000 - endDate: '2014-02-03T00:00:00-08:00' - endDateMs: 1391414400000 - summaries: - - date: '2014-02-03T00:00:00-08:00' - dateMs: 1391414400000 - total: 14 - deleted: 0 - size: 7000000 - duration: 70 - viewed: 7 - favourite: 0 - - date: '2014-02-02T00:00:00-08:00' - dateMs: 1391328000000 - total: 12 - deleted: 3 - size: 6000000 - duration: 60 - viewed: 6 - favourite: 2 - - date: '2014-02-01T00:00:00-08:00' - dateMs: 1391241600000 - total: 10 - deleted: 1 - size: 5000000 - duration: 50 - viewed: 5 - favourite: 4 - - - /cloud/json/fileDevices: - get: - summary: Get File Devices - operationId: Get File Devices - description: Return all combinations of device ID's and device descriptions from existing user files. - tags: - - Device Files - security: - - userApiKey: [] - parameters: - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - responses: - '200': - description: File Devices - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - devices: - type: array - items: - type: object - properties: - id: - type: string - description: Device ID - desc: - type: string - description: Device name/description + description: Degrees this video has been rotated. It is up to the playback mechanism to rotate the video upright again, if necessary. + incomplete: + type: boolean + description: If the file's upload is not completed yet + device: + type: object + description: Assosiated device instance + properties: + id: + type: string + type: + type: integer + desc: + type: string required: - id - - desc + - type + - name + - thumbnail + - viewed + - favourite + - viewCount + - publicAccess + - creationDate + - creationTime + - size + - incomplete + - device example: resultCode: 0 - devices: - - id: CAMERA_ID_0 - desc: Front door - - id: CAMERA_ID_1 - desc: Kitchen - - id: CAMERA_ID_2 - desc: Back door + tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ + tempKeyExpire: '2013-07-01T14:54:54-04:00' + totalFilesSpace: 10485760 + files: + - id: 123 + type: 1 + name: 123.mp4 + thumbnail: false + viewed: true + favourite: false + viewCount: 1 + publicAccess: false + creationDate: '2013-06-05T16:43:59-07:00' + creationTime: 1370475839000 + size: 3479190 + duration: 60 + rotate: 180 + incomplete: false + device: + id: ABC123 + type: 21 + desc: Living room camera + - id: 124 + type: 2 + name: 124.jpg + thumbnail: true + viewed: false + favourite: false + viewCount: 2 + publicAccess: false + creationDate: '2013-06-05T16:43:59-07:00' + creationTime: 1370475839000 + size: 347919 + rotate: 0 + incomplete: true + device: + id: ABC124 + type: 21 + desc: Door camera - /cloud/json/filesInfo/{fileId}: - get: - summary: Get Device File Information - operationId: Get Device File Information - description: For public files the API key header is optional. + /cloud/json/files/{fileId}: + post: + summary: Upload Device File Fragment + operationId: Upload Device File Fragment + description: |- + Allow to add a fragment to the content of the existing file or upload a thumbnail. + + `Content-Type` and `PPCAuthorization` must set the same way as in uploading a new file. tags: - Device Files - security: - - userApiKey: [] parameters: - name: fileId in: path - description: File ID of the file for which to retrieve information + description: Existing file ID required: true schema: type: integer - - name: locationId + - name: proxyId in: query - description: File location ID + description: Device ID of the proxy that this file is being uploaded through required: true schema: - type: integer - responses: - '200': - description: File's info - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - file: - type: object - properties: - id: - type: integer - type: - type: integer - name: - type: string - thumbnail: - type: boolean - viewed: - type: boolean - favourite: - type: boolean - viewCount: - type: integer - publicAccess: - type: boolean - creationDate: - type: string - creationDateMs: - type: integer - size: - type: integer - duration: - type: integer - rotate: - type: integer - incomplete: - type: boolean - device: - type: object - properties: - id: - type: string - type: - type: integer - desc: - type: string - example: - resultCode: 0 - tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ - tempKeyExpire: '2013-07-01T14:54:54-04:00' - tempKeyExpireMs: 1372704894000 - file: - id: 123 - type: 1 - name: 123.mp4 - thumbnail: false - viewed: true - favourite: false - viewCount: 1 - publicAccess: false - creationDate: '2013-06-05T16:43:59-07:00' - creationDateMs: 1370475839000 - size: 3479190 - duration: 60 - rotate: 180 - incomplete: false - device: - id: ABC123 - type: 21 - desc: Living room camera - - - /cloud/json/files/{fileId}/report/{reportType}: - put: - summary: Report Abuse - operationId: Report Device File Abuse - description: |- - The API Key should only be used if a user is logged in and reporting abuse, - and helps support / administrators understand and communicate with the person who is reporting the complaint. - If the user is not logged into the system and is instead browsing publicly, then you do not have to include an API key in the header. - tags: - - Device Files - security: - - userApiKey: [] - parameters: - - name: fileId - in: path - description: File ID to report - required: true + type: string + - name: thumbnail + in: query + description: true - the content is a thumbnail image schema: - type: integer - - name: reportType - in: path + type: boolean + - name: incomplete + in: query description: >- - Type of report. - This is typically `abuse`, but may be changed to trigger a different type of email template to support / administrators. - required: true + true - The file will be extended later +
false - This file is complete + schema: + type: boolean + - name: index + in: query + description: >- + Fragment index starting from 0 to identify unique file fragment. + It is used for additional control over uploaded data. + schema: + type: integer + - name: PPCAuthorization + in: header + description: Device's authorization + example: esp token=ABC12345 schema: type: string responses: @@ -13149,229 +12735,256 @@ paths: schema: type: object properties: - resultCode: + status: + type: string + description: Device response status + filesAction: + type: integer + enum: [1,2] + description: >- + Actions performed by the API as a result of this file upload: +
1 - Old files have been deleted to make room for this one +
2 - There isn't enough space to upload this file + totalFilesSpace: + type: integer + description: The total space in the user's account for files in bytes. + usedFilesSpace: + type: integer + description: The space in the user's account that has already been consumed in bytes. + fragments: type: integer + description: The total fragments that compose this file. example: - resultCode: 0 - + status: ACK + filesAction: 1 + thumbnail: true + totalFilesSpace: 10000000 + usedFilesSpace: 1000000 + fragments: 3 - /cloud/json/appfiles: - post: - summary: Upload Application File Content - operationId: Upload App File Content + get: + summary: Download Device File + operationId: Download Device File description: |- - The "Content-Type" header must be like `image/*`, `video/*`, `audio/*` or `application/octet-stream`. + The `Range` HTTP Header is optional, and will only return a chunk of the total content. + If used, it is recommended to select a range that is a multiple of 10240 bytes. - For example: `image/jpeg`, `video/mp4`, `audio/mp3`. + See https://www.rfc-editor.org/rfc/rfc9110.html#name-accept-ranges for a discussion on the header options. + + A temporary API key provided in the query parameter may be used to forward a link to other part of the app. + A temporary API key can be obtained by calling the loginByKey API. + It is expired soon after receiving. tags: - - Application Files + - Device Files security: - userApiKey: [] + - tempApiKey: [] + - botApiKey: [] parameters: - name: fileId - in: query - description: Existing file ID to replace the content and properties - schema: - type: integer - - name: type - in: query - description: File type + in: path + description: File ID to download required: true schema: type: integer - - name: userId - in: query - description: User ID associated with this file. It can be used by organization administrators to upload files on other user accounts. - schema: - type: integer - - name: locationId - in: query - description: Location ID associated with this file - schema: - type: integer - - name: deviceId + - name: thumbnail in: query - description: Device ID associated with this file + description: >- + true - Download the thumbnail for this file +
false - Download the actual file, not the thumbnail, default schema: - type: string - - name: name - in: query - description: File name + type: boolean + - name: Range + in: header + description: Data range + example: bytes=10240-20479 schema: type: string - - name: publicAccess - in: query - description: Publicly available file - schema: - type: boolean responses: '200': - description: OK - content: - application/json: + description: OK. The file content is returned in full. + headers: + Accept-Ranges: schema: - type: object - properties: - resultCode: - type: integer - fileId: - type: integer - example: - resultCode: 0 - fileId: 123 + type: string + description: Accepted content range values in bytes + Content-Type: + schema: + type: string + description: The file's content type + Content-Length: + schema: + type: integer + Last-Modified: + schema: + type: string + description: The file's creation date + Content-Range: + schema: + type: string + description: >- + If the `Range` of the content was requested. + This will be in the format of `bytes {start}-{end}/{total size}`. + For example: `Content-Range: bytes 21010-47021/47022`. + Content-Disposition: + schema: + type: string + description: The filename when the whole file is requested. + ETag: + schema: + type: string + description: The file's ID + '204': + description: No Content. The file exist, but the content is not available for this request. + '206': + description: Partial Content. The file content is partially returned. + headers: + Accept-Ranges: + schema: + type: string + description: Accepted content range values in bytes + Content-Type: + schema: + type: string + description: The file's content type + Content-Length: + schema: + type: integer + Last-Modified: + schema: + type: string + description: The file's creation date + Content-Range: + schema: + type: string + description: >- + If the `Range` of the content was requested. +
This will be in the format of `bytes {start}-{end}/{total size}`. +
For example: `Content-Range: bytes 21010-47021/47022`. + Content-Disposition: + schema: + type: string + description: The filename when the whole file is requested. + ETag: + schema: + type: string + description: The file's ID + '401': + description: Unauthorized. The API key is wrong. + '404': + description: Not Found. The file does not exist. + '500': + description: Internal error. Something went wrong on our side. - get: - summary: Get Application Files - operationId: Get App Files + put: + summary: Update Device File Attributes + operationId: Update Device File Attributes description: |- - Return a list of the user's files filtered by query parameters. - - API key - optional to get publicly available files. + Update the file's attributes to declare, if the file has been viewed or not, + if it's a favourite file and shouldn't be auto-deleted, and whether the file is available for public access. + + The file publisher (camera) can update it as completed. + + Also, this API can be used to recover deleted files. tags: - - Application Files + - Device Files security: - userApiKey: [] parameters: - name: fileId - in: query - description: File ID filter + in: path + description: File ID to update + required: true schema: type: integer - - name: type + - name: locationId in: query - description: File type + description: File location ID + required: true schema: type: integer - - name: userId + - name: proxyId in: query - description: User ID associated with this file. It can be used by organization administrators to access other user accounts. + description: Device ID of the proxy that this file is being uploaded through schema: - type: integer - - name: locationId + type: string + - name: incomplete in: query - description: Location ID associated with this file + description: Set it to false for updating the file as completed schema: - type: integer - - name: deviceId + type: boolean + - name: recover in: query - description: Device ID associated with this file + description: Set it to true to recover a deleted file schema: - type: string - - name: name + type: boolean + - name: pure in: query - description: File name + description: true - the server will not make any modification of the file content + schema: + type: boolean + - name: PPCAuthorization + in: header + description: Device's authorization (required for updating file as completed) + example: esp token=ABC12345 schema: type: string - responses: - '200': - description: Files info - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - tempKey: - type: string - description: Temporary API key, which can be used to download the files content and obtain files information. - tempKeyExpire: - type: string - description: Temporary API key expiry - files: - type: array - items: - type: object - properties: - id: - type: integer - description: File ID - type: - type: integer - description: File Type - name: - type: string - description: File Name - size: - type: integer - description: Size of the file in bytes - userId: - type: integer - description: User ID associated with this file - locationId: - type: integer - description: Location ID associated with this file - deviceId: - type: string - description: Device ID associated with this file - publicAccess: - type: boolean - description: If it is publicly acessible (without login) - required: - - id - - type - - name - - size - - publicAccess + requestBody: + content: + application/json: + example: + file: + viewed: true + favourite: true + publicAccess: true + schema: + type: object + properties: + file: + type: object + properties: + viewed: + type: boolean + favourite: + type: boolean + publicAccess: + type: boolean + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer example: resultCode: 0 - tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ - tempKeyExpire: '2013-07-01T14:54:54-04:00' - files: - - id: 123 - type: 1 - name: AVATAR - size: 34790 - userId: 123 - publicAccess: true - - id: 124 - type: 2 - name: MAP - size: 39190 - locationId: 123 - publicAccess: false - - id: 125 - type: 3 - name: INSTALLATION - size: 39190 - deviceId: ABC123 - publicAccess: false - - /cloud/json/appfiles/{fileId}/url: - get: - summary: Get Application File Download URL - operationId: Get App File Download URL - description: Get a temporary URL to download the file's content directly from S3. + delete: + summary: Delete Device File + operationId: Delete Device File tags: - - Application Files + - Device Files security: - userApiKey: [] parameters: - name: fileId in: path - description: File ID to download + description: File ID to delete required: true schema: type: integer - name: locationId in: query - description: Location ID to download the file - schema: - type: integer - - name: userId - in: query - description: User ID to download the file - schema: - type: integer - - name: expiration - in: query - description: URL's expiration in milliseconds since the current time + description: File location ID + required: true schema: type: integer responses: '200': - description: Content URL + description: OK content: application/json: schema: @@ -13379,29 +12992,21 @@ paths: properties: resultCode: type: integer - contentUrl: - type: string example: resultCode: 0 - contentUrl: >- - https://s3.amazonaws.com/bucket1/object1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180704T220443Z&X-Amz-SignedHeaders=host&X-Amz-Expires=10&X-Amz-Credential=AKIAJPAZD&X-Amz-Signature=af7329c26 - /cloud/json/appfiles/{fileId}: + /cloud/json/files/{fileId}/url: get: - summary: Download Application File - operationId: Download App File - description: |- - The `Range` HTTP Header is optional, and will only return a chunk of the total content. - - A temporary API key provided in the query parameter may be used to forward a link to other part of the app. - A temporary API key can be obtained by calling the loginByKey API. - It is expired soon after receiving. + summary: Get Device File Download URL + operationId: Get Device File Download URL + description: >- + A client can request temporary download URL's to get file and thumbnail + content directly from S3 instead of copying it through the server. tags: - - Application Files + - Device Files security: - userApiKey: [] - - tempApiKey: [] parameters: - name: fileId in: path @@ -13409,105 +13014,30 @@ paths: required: true schema: type: integer - - name: userId - in: query - description: User ID to download the file as an administrator - schema: - type: integer - name: locationId in: query - description: Location ID to download the file as an administrator + description: File location ID + required: true schema: type: integer - - name: attach + - name: content in: query - description: Download the file content as an attachments with the Content-Disposition header + description: Request file content URL schema: type: boolean - - name: Range - in: header - description: Optional request of a part of the file content - example: bytes=10240-20479 - schema: - type: string - responses: - '200': - description: OK. The file content is returned in full. - headers: - Accept-Ranges: - schema: - type: string - description: Accepted content range values in bytes - Content-Type: - schema: - type: string - description: The file's content type - Content-Length: - schema: - type: integer - Content-Transfer-Encoding: - schema: - type: string - description: binary when the whole file is requested as attachment - Content-Disposition: - schema: - type: string - description: The filename when the whole file is requested as attachment. - '206': - description: Partial Content. The file content is partially returned. - headers: - Accept-Ranges: - schema: - type: string - description: Accepted content range values in bytes - Content-Type: - schema: - type: string - description: The file's content type - Content-Length: - schema: - type: integer - Content-Range: - schema: - type: string - description: >- - If the `Range` of the content was requested. -
This will be in the format of `bytes {start}-{end}/{total size}`. -
For example: `Content-Range: bytes 21010-47021/47022`. - '401': - description: Unauthorized. The API key is wrong. - '404': - description: Not Found. The file does not exist. - '500': - description: Internal error. Something went wrong on our side. - - delete: - summary: Delete Application File - operationId: Delete App File - tags: - - Application Files - security: - - userApiKey: [] - parameters: - - name: fileId - in: path - description: File ID to delete - required: true - schema: - type: integer - - name: userId + - name: thumbnail in: query - description: User ID to delete the file as an administrator + description: Request thumbnail content URL schema: - type: integer - - name: locationId + type: boolean + - name: expiration in: query - description: Location ID to delete the file as an administrator + description: URL's expiration in milliseconds since the current time schema: type: integer responses: '200': - description: OK + description: File content and thumbnail URLs content: application/json: schema: @@ -13515,34 +13045,99 @@ paths: properties: resultCode: type: integer + contentUrl: + type: string + thumbnailUrl: + type: string example: resultCode: 0 + contentUrl: >- + https://s3.amazonaws.com/bucket1/object1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180704T220443Z&X-Amz-SignedHeaders=host&X-Amz-Expires=10&X-Amz-Credential=AKIAJPAZD&X-Amz-Signature=af7329c26 + thumbnailUrl: >- + https://s3.amazonaws.com/bucket2/object1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180704T220443Z&X-Amz-SignedHeaders=host&X-Amz-Expires=10&X-Amz-Credential=AKIAJPAZD&X-Amz-Signature=af7329c26 - /cloud/json/ruleConditions: + /cloud/json/filesSummary/{aggregation}: get: - summary: Get Rule Phrases - operationId: Get Rule Phrases - description: Get possible rule triggers, states, and actions + summary: Get Summary of Device Files + operationId: Get Summary of Device Files + description: |- + Users can collect a massive list of files. Even the plain text to describe these files can sometimes be megabytes long. + This API helps describe what files exist on the server, so the user can drill into the data without downloading everything all at once. + + If is highly recommended to call this API first and then use received information to obtain files list for specific time period. + + In some cases even files summary data can be very long. + So it is recommended to use optional `startDate` and `endDate` parameters. + By default `endDate` is set to the creation time of the last uploaded user file. + If `startDate` is not provided, it will be estimated by the cloud according to the aggregation to provide better API performance. + + This API will return a summary of files grouped by files creation date in descending order by default, + providing summary information for the files within each aggregation period (day, week, month, etc.). + + For better API performance request only own user files information with aggregation by days without details and for limited time period. tags: - - Rules Engine + - Device Files security: - userApiKey: [] parameters: + - name: aggregation + in: path + description: >- + The duration of time across which to aggregate summary information +
1 - hour +
2 - day +
3 - month +
4 - 7-day week from Sunday to Saturday + required: true + schema: + type: integer + enum: [1,2,3,4] - name: locationId in: query - description: Location ID + description: Files location ID required: true schema: type: integer - - name: version + - name: details in: query - description: Rules implementation version + description: >- + If true, the API will return detailed information - slow. +
Otherwise only total number of files will be returned. + schema: + type: boolean + - name: timeZone + in: query + description: >- + Time zone ID to separate aggregated summary information. +
For example, `America/Los_Angeles`. + schema: + type: string + - name: type + in: query + description: >- + Filter by type of file. +
0 - any file +
1 - videos only +
2 - images only +
3 - audio only +
4 - bitmaps only schema: type: integer + enum: [0,1,2,3,4] + - name: startDate + in: query + description: Start date for which to begin returning aggregate summary information on the user's files + schema: + type: string + - name: endDate + in: query + description: End date for which to stop returning aggregate summary information on the user's files + schema: + type: string responses: '200': - description: Triggers, states, and actions + description: Files summary content: application/json: schema: @@ -13550,616 +13145,502 @@ paths: properties: resultCode: type: integer - triggers: + totalFilesSpace: + type: integer + description: The total space in the user's account for files in bytes. + usedFilesSpace: + type: integer + description: The space in the user's account that has already been consumed in bytes. + filesCount: + type: integer + description: Number of files + startDate: + type: string + description: Date when first file uploaded + startDateMs: + type: integer + endDate: + type: string + description: Date when last file uploaded + endDateMs: + type: integer + summaries: type: array + description: Information for the files within each aggregation period items: type: object properties: - id: - type: integer - name: + date: type: string - type: - type: integer - display: + description: The beginning of an aggregation period + dateMs: type: integer - timezone: - type: boolean - desc: - type: string - past: - type: string - functionGroup: - type: string - parameters: - type: array - items: - type: object - properties: - name: - type: string - category: - type: integer - optional: - type: boolean - desc: - type: string - values: - type: array - items: - type: object - properties: - id: - type: string - name: - type: string - required: - - id - - name - value: - type: string - valueType: - type: integer - unit: - type: string - minValue: - type: string - maxValue: - type: string - required: - - name - - category - - optional - - desc - - values - required: - - id - - name - - type - - display - - timezone - - desc - - past - - parameters - states: - type: array - items: - type: object - properties: - id: + total: type: integer - name: - type: string - type: + description: Number of files + deleted: type: integer - display: + description: Number of deleted files + size: type: integer - timezone: - type: boolean - desc: - type: string - past: - type: string - parameters: - type: array - items: - type: object - properties: - name: - type: string - category: - type: integer - optional: - type: boolean - desc: - type: string - values: - type: array - items: - type: object - properties: - id: - type: string - name: - type: string - required: - - id - - name - required: - - name - - category - - optional - - desc - - values - functionGroup: - type: string - required: - - id - - name - - type - - display - - timezone - - desc - - past - - parameters - actions: - type: array - items: - type: object - properties: - id: + description: Total files size in bytes, if details requested + duration: type: integer - name: - type: string - type: + description: Total files duration, if details requested + viewed: type: integer - display: + description: Number of viewed files, if details requested + favourite: type: integer - timezone: - type: boolean - desc: - type: string - past: - type: string - parameters: - type: array - items: - type: object - properties: - name: - type: string - category: - type: integer - optional: - type: boolean - desc: - type: string - values: - type: array - items: - type: object - properties: - id: - type: string - name: - type: string - selectorValue: - type: string - required: - - id - - name - - selectorValue - selectorName: - type: string - required: - - name - - category - - optional - - desc - - values + description: Number of favourite files, if details requested + required: + - date + - dateMs + - total + - deleted + example: + resultCode: 0 + totalFilesSpace: 10485760 + usedFilesSpace: 1043858 + filesCount: 36 + startDate: '2014-02-01T00:00:00-08:00' + startDateMs: 1391241600000 + endDate: '2014-02-03T00:00:00-08:00' + endDateMs: 1391414400000 + summaries: + - date: '2014-02-03T00:00:00-08:00' + dateMs: 1391414400000 + total: 14 + deleted: 0 + size: 7000000 + duration: 70 + viewed: 7 + favourite: 0 + - date: '2014-02-02T00:00:00-08:00' + dateMs: 1391328000000 + total: 12 + deleted: 3 + size: 6000000 + duration: 60 + viewed: 6 + favourite: 2 + - date: '2014-02-01T00:00:00-08:00' + dateMs: 1391241600000 + total: 10 + deleted: 1 + size: 5000000 + duration: 50 + viewed: 5 + favourite: 4 + + + /cloud/json/fileDevices: + get: + summary: Get File Devices + operationId: Get File Devices + description: Return all combinations of device ID's and device descriptions from existing user files. + tags: + - Device Files + security: + - userApiKey: [] + parameters: + - name: locationId + in: query + description: Location ID + required: true + schema: + type: integer + responses: + '200': + description: File Devices + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + devices: + type: array + items: + type: object + properties: + id: + type: string + description: Device ID + desc: + type: string + description: Device name/description required: - id - - name - - type - - display - - timezone - desc - - parameters example: resultCode: 0 - triggers: - - id: 5 - name: schedule - type: 11 - display: 11 - timezone: true - desc: $schedule - past: $schedule - functionGroup: schedule - parameters: - - name: schedule - category: 2 - optional: false - desc: What time? - - name: timeZone - category: 3 - optional: false - desc: Is this timezone OK? - - id: 10 - name: Device offline - type: 11 - display: 13 - timezone: true - desc: goes offline - past: went offline - parameters: - - name: deviceId - category: 5 - optional: false - desc: device - values: - - id: 470FF274-8700-44AB-A273-A70691A3C140::4 - name: moss mobile 6 - - id: ea5101a8005f-10031-470 - name: Gateway - - id: 22 - name: Smart plug turned off trigger - type: 14 - display: 14 - timezone: false - desc: switches off - past: switched off - parameters: - - name: deviceId - category: 5 - optional: false - desc: smart plug - values: - - id: 470FF274-8700-44AB-A273-A70691A3C140::4 - name: moss mobile 6 - - id: 77 - name: Door open timer - type: 15 - display: 13 - timezone: false - desc: is opened for $minutes minutes - past: was opened for $minutes minutes - parameters: - - name: deviceId - category: 5 - optional: false - desc: entry sensor - values: - - id: 12345ABCDEF - name: Front Door - - name: minutes - category: 1 - optional: false - desc: How long in minutes? - value: '5' - valueType: 1 - unit: minute - minValue: '1' - maxValue: '120' - states: - - id: 9 - name: Location state - type: 21 - display: 22 - timezone: false - desc: am - past: was - parameters: - - name: locationId - category: 4 - optional: false - desc: my location - values: - - id: '5' - name: David Moss - - name: event - category: 13 - optional: false - desc: state - values: - - id: HOME - name: Home - - id: AWAY - name: Away - - id: VACATION - name: Vacation - - id: 18 - name: Device online - type: 21 - display: 23 - timezone: true - desc: is online - past: was online - functionGroup: online - parameters: - - name: deviceId - category: 5 - optional: false - desc: device - values: - - id: 470FF274-8700-44AB-A273-A70691A3C140::4 - name: moss mobile 6 - - id: ea5101a8005f-10031-470 - name: Gateway - - id: 19 - name: Device offline - type: 21 - display: 23 - timezone: true - desc: is offline - past: was offline - - id: 23 - name: Smart plug is on state + devices: + - id: CAMERA_ID_0 + desc: Front door + - id: CAMERA_ID_1 + desc: Kitchen + - id: CAMERA_ID_2 + desc: Back door + + + /cloud/json/filesInfo/{fileId}: + get: + summary: Get Device File Information + operationId: Get Device File Information + description: For public files the API key header is optional. + tags: + - Device Files + security: + - userApiKey: [] + parameters: + - name: fileId + in: path + description: File ID of the file for which to retrieve information + required: true + schema: + type: integer + - name: locationId + in: query + description: File location ID + required: true + schema: + type: integer + responses: + '200': + description: File's info + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + file: + type: object + properties: + id: + type: integer + type: + type: integer + name: + type: string + thumbnail: + type: boolean + viewed: + type: boolean + favourite: + type: boolean + viewCount: + type: integer + publicAccess: + type: boolean + creationDate: + type: string + creationDateMs: + type: integer + size: + type: integer + duration: + type: integer + rotate: + type: integer + incomplete: + type: boolean + device: + type: object + properties: + id: + type: string + type: + type: integer + desc: + type: string + example: + resultCode: 0 + tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ + tempKeyExpire: '2013-07-01T14:54:54-04:00' + tempKeyExpireMs: 1372704894000 + file: + id: 123 + type: 1 + name: 123.mp4 + thumbnail: false + viewed: true + favourite: false + viewCount: 1 + publicAccess: false + creationDate: '2013-06-05T16:43:59-07:00' + creationDateMs: 1370475839000 + size: 3479190 + duration: 60 + rotate: 180 + incomplete: false + device: + id: ABC123 type: 21 - display: 23 - timezone: false - desc: is switched on - past: was switched on - parameters: - - name: deviceId - category: 5 - optional: false - desc: smart plug - values: - - id: 470FF274-8700-44AB-A273-A70691A3C140::4 - name: moss mobile 6 - actions: - - id: 4 - name: GP notification to phone - type: 31 - display: 31 - timezone: false - desc: send a notification to my phone - past: sent a notification to my phone - parameters: - - name: text - category: 10 - optional: false - desc: notification text - - id: 40 - name: Camera alert me with a picture - type: 33 - display: 33 - timezone: false - desc: alert me with a picture - parameters: - - name: deviceId - category: 5 - optional: false - desc: Camera - values: - - id: 470FF274-8700-44AB-A273-A70691A3C140::4 - name: moss mobile 6 - - id: ea5101a8005f-10031-470 - name: Gateway - - id: virtualpsm-6-4e7 - name: Light - - id: 41 - name: Camera point to vantage point action - type: 33 - display: 33 - timezone: false - desc: point to my '$point' vantage point - parameters: - - name: deviceId - category: 5 - values: - - id: CAMERA_ID_1 - name: Living Room Camera - - id: CAMERA_ID_2 - name: Bedroom Camera - - name: point - category: 15 - selectorName: deviceId - values: - - id: '0' - name: Front Door - selectorValue: CAMERA_ID_1 - - id: '1' - name: Front Window - selectorValue: CAMERA_ID_1 - - id: '0' - name: Bedroom Door - selectorValue: CAMERA_ID_2 - - id: '1' - name: Bedroom Window - selectorValue: CAMERA_ID_2 + desc: Living room camera - /cloud/json/rules: + /cloud/json/files/{fileId}/report/{reportType}: + put: + summary: Report Abuse + operationId: Report Device File Abuse + description: |- + The API Key should only be used if a user is logged in and reporting abuse, + and helps support / administrators understand and communicate with the person who is reporting the complaint. + If the user is not logged into the system and is instead browsing publicly, then you do not have to include an API key in the header. + tags: + - Device Files + security: + - userApiKey: [] + parameters: + - name: fileId + in: path + description: File ID to report + required: true + schema: + type: integer + - name: reportType + in: path + description: >- + Type of report. + This is typically `abuse`, but may be changed to trigger a different type of email template to support / administrators. + required: true + schema: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + + /cloud/json/appfiles: post: - summary: Create a Rule - operationId: Create a Rule + summary: Upload Application File Content + operationId: Upload App File Content description: |- - When creating a rule, specify a single trigger, one or more states, and one or more actions, - by referencing the ID's of the triggers / states / actions that are available to the user through the GET API. + The "Content-Type" header must be like `image/*`, `video/*`, `audio/*` or `application/octet-stream`. - States are OR'd together by default, unless wrapped in an AND block. - This is to provide flexibility to the developer to implement, but we recommend only defining states inside AND blocks to keep the UI simple to understand. + For example: `image/jpeg`, `video/mp4`, `audio/mp3`. + tags: + - Application Files + security: + - userApiKey: [] + parameters: + - name: fileId + in: query + description: Existing file ID to replace the content and properties + schema: + type: integer + - name: type + in: query + description: File type + required: true + schema: + type: integer + - name: userId + in: query + description: User ID associated with this file. It can be used by organization administrators to upload files on other user accounts. + schema: + type: integer + - name: locationId + in: query + description: Location ID associated with this file + schema: + type: integer + - name: deviceId + in: query + description: Device ID associated with this file + schema: + type: string + - name: name + in: query + description: File name + schema: + type: string + - name: publicAccess + in: query + description: Publicly available file + schema: + type: boolean + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + fileId: + type: integer + example: + resultCode: 0 + fileId: 123 + + get: + summary: Get Application Files + operationId: Get App Files + description: |- + Return a list of the user's files filtered by query parameters. + + API key - optional to get publicly available files. + tags: + - Application Files + security: + - userApiKey: [] + parameters: + - name: fileId + in: query + description: File ID filter + schema: + type: integer + - name: type + in: query + description: File type + schema: + type: integer + - name: userId + in: query + description: User ID associated with this file. It can be used by organization administrators to access other user accounts. + schema: + type: integer + - name: locationId + in: query + description: Location ID associated with this file + schema: + type: integer + - name: deviceId + in: query + description: Device ID associated with this file + schema: + type: string + - name: name + in: query + description: File name + schema: + type: string + responses: + '200': + description: Files info + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + tempKey: + type: string + description: Temporary API key, which can be used to download the files content and obtain files information. + tempKeyExpire: + type: string + description: Temporary API key expiry + files: + type: array + items: + type: object + properties: + id: + type: integer + description: File ID + type: + type: integer + description: File Type + name: + type: string + description: File Name + size: + type: integer + description: Size of the file in bytes + userId: + type: integer + description: User ID associated with this file + locationId: + type: integer + description: Location ID associated with this file + deviceId: + type: string + description: Device ID associated with this file + publicAccess: + type: boolean + description: If it is publicly acessible (without login) + required: + - id + - type + - name + - size + - publicAccess + example: + resultCode: 0 + tempKey: UugJtGEXxMfnVyql4N4crIAfqOUlJ + tempKeyExpire: '2013-07-01T14:54:54-04:00' + files: + - id: 123 + type: 1 + name: AVATAR + size: 34790 + userId: 123 + publicAccess: true + - id: 124 + type: 2 + name: MAP + size: 39190 + locationId: 123 + publicAccess: false + - id: 125 + type: 3 + name: INSTALLATION + size: 39190 + deviceId: ABC123 + publicAccess: false - If a trigger / state / action requires a parameter, the parameter must be filled out completely. - It is possible to save a rule that is not complete. The Care Daily AI Platform will not execute partial rules. + /cloud/json/appfiles/{fileId}/url: + get: + summary: Get Application File Download URL + operationId: Get App File Download URL + description: Get a temporary URL to download the file's content directly from S3. tags: - - Rules Engine + - Application Files security: - userApiKey: [] parameters: - - name: locationId - in: query - description: Location ID + - name: fileId + in: path + description: File ID to download required: true schema: type: integer - requestBody: - content: - application/json: - example: - rule: - status: 1 - timeZone: US/Pacific - hidden: false - trigger: - id: 121 - parameter: - - name: schedule - value: 0 30 16 * * ? - - name: locationId - value: '123' - calendar: - - include: false - startTime: 3600 - endTime: 4200 - - include: false - daysOfWeek: 65 - states: - state: - - id: 125 - parameter: - - name: temp - value: '25' - - id: 129 - parameter: - - name: event - value: home - and: - - state: - - id: 123 - parameter: - - name: deviceId - value: ABC123 - - id: 124 - parameter: - - name: locationId - value: '125' - - state: - - id: 130 - parameter: - - name: deviceId - value: ABC123 - - id: 131 - parameter: - - name: locationId - value: '125' - actions: - action: - - id: 126 - - id: 127 - parameter: - - name: deviceId - value: AC123 - - name: index - value: '0' - schema: - type: object - properties: - rule: - type: object - properties: - status: - type: integer - timeZone: - type: string - hidden: - type: boolean - trigger: - type: object - properties: - id: - type: integer - parameter: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - required: - - name - - value - calendar: - type: array - items: - type: object - properties: - include: - type: boolean - startTime: - type: integer - endTime: - type: integer - daysOfWeek: - type: integer - required: - - include - states: - type: object - properties: - state: - type: array - items: - type: object - properties: - id: - type: integer - parameter: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - required: - - name - - value - required: - - id - - parameter - and: - type: array - items: - type: object - properties: - state: - type: array - items: - type: object - properties: - id: - type: integer - parameter: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - required: - - name - - value - required: - - id - - parameter - required: - - state - actions: - type: object - properties: - action: - type: array - items: - type: object - properties: - id: - type: integer - parameter: - type: array - items: - type: object - properties: - name: - type: string - value: - type: string - required: - - name - - value - required: - - id + - name: locationId + in: query + description: Location ID to download the file + schema: + type: integer + - name: userId + in: query + description: User ID to download the file + schema: + type: integer + - name: expiration + in: query + description: URL's expiration in milliseconds since the current time + schema: + type: integer responses: '200': - description: OK + description: Content URL content: application/json: schema: @@ -14167,55 +13648,135 @@ paths: properties: resultCode: type: integer - rule: - type: object - properties: - id: - type: integer - description: Created rule ID + contentUrl: + type: string example: resultCode: 0 - rule: - id: 1234 + contentUrl: >- + https://s3.amazonaws.com/bucket1/object1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180704T220443Z&X-Amz-SignedHeaders=host&X-Amz-Expires=10&X-Amz-Credential=AKIAJPAZD&X-Amz-Signature=af7329c26 + + /cloud/json/appfiles/{fileId}: get: - summary: Get Rules - operationId: Get Rules - description: This API will allow you to filter the list of rules by criteria. + summary: Download Application File + operationId: Download App File + description: |- + The `Range` HTTP Header is optional, and will only return a chunk of the total content. + + A temporary API key provided in the query parameter may be used to forward a link to other part of the app. + A temporary API key can be obtained by calling the loginByKey API. + It is expired soon after receiving. tags: - - Rules Engine + - Application Files security: - userApiKey: [] - - botApiKey: [] + - tempApiKey: [] parameters: + - name: fileId + in: path + description: File ID to download + required: true + schema: + type: integer + - name: userId + in: query + description: User ID to download the file as an administrator + schema: + type: integer - name: locationId in: query - description: Location ID - required: true + description: Location ID to download the file as an administrator schema: type: integer - - name: ruleId + - name: attach in: query - description: Only return this rule + description: Download the file content as an attachments with the Content-Disposition header + schema: + type: boolean + - name: Range + in: header + description: Optional request of a part of the file content + example: bytes=10240-20479 schema: type: string - - name: deviceId + responses: + '200': + description: OK. The file content is returned in full. + headers: + Accept-Ranges: + schema: + type: string + description: Accepted content range values in bytes + Content-Type: + schema: + type: string + description: The file's content type + Content-Length: + schema: + type: integer + Content-Transfer-Encoding: + schema: + type: string + description: binary when the whole file is requested as attachment + Content-Disposition: + schema: + type: string + description: The filename when the whole file is requested as attachment. + '206': + description: Partial Content. The file content is partially returned. + headers: + Accept-Ranges: + schema: + type: string + description: Accepted content range values in bytes + Content-Type: + schema: + type: string + description: The file's content type + Content-Length: + schema: + type: integer + Content-Range: + schema: + type: string + description: >- + If the `Range` of the content was requested. +
This will be in the format of `bytes {start}-{end}/{total size}`. +
For example: `Content-Range: bytes 21010-47021/47022`. + '401': + description: Unauthorized. The API key is wrong. + '404': + description: Not Found. The file does not exist. + '500': + description: Internal error. Something went wrong on our side. + + delete: + summary: Delete Application File + operationId: Delete App File + tags: + - Application Files + security: + - userApiKey: [] + parameters: + - name: fileId + in: path + description: File ID to delete + required: true + schema: + type: integer + - name: userId in: query - description: Only return rules for the given device ID + description: User ID to delete the file as an administrator schema: - type: string - - name: details + type: integer + - name: locationId in: query - description: |- - true - Return details for this rule, including all the triggers, states, and actions that compose the rule. -
- false - Only return the high level information about the rule, including the id, description text, - on/off status, whether the rule is a default rule, and whether the rule is hidden and not editable, default + description: Location ID to delete the file as an administrator schema: - type: boolean + type: integer responses: '200': - description: Rules + description: OK content: application/json: schema: @@ -14223,7 +13784,113 @@ paths: properties: resultCode: type: integer - rules: + example: + resultCode: 0 + + + /cloud/json/ruleConditions: + get: + summary: Get Rule Phrases + operationId: Get Rule Phrases + description: Get possible rule triggers, states, and actions + tags: + - Rules Engine + security: + - userApiKey: [] + parameters: + - name: locationId + in: query + description: Location ID + required: true + schema: + type: integer + - name: version + in: query + description: Rules implementation version + schema: + type: integer + responses: + '200': + description: Triggers, states, and actions + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + triggers: + type: array + items: + type: object + properties: + id: + type: integer + name: + type: string + type: + type: integer + display: + type: integer + timezone: + type: boolean + desc: + type: string + past: + type: string + functionGroup: + type: string + parameters: + type: array + items: + type: object + properties: + name: + type: string + category: + type: integer + optional: + type: boolean + desc: + type: string + values: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + required: + - id + - name + value: + type: string + valueType: + type: integer + unit: + type: string + minValue: + type: string + maxValue: + type: string + required: + - name + - category + - optional + - desc + - values + required: + - id + - name + - type + - display + - timezone + - desc + - past + - parameters + states: type: array items: type: object @@ -14232,303 +13899,346 @@ paths: type: integer name: type: string - secondName: - type: string - status: + type: type: integer - hidden: - type: boolean - default: - type: boolean - goalId: + display: type: integer - trigger: - type: object - properties: - id: - type: integer - name: - type: string - type: - type: integer - display: - type: integer - timezone: - type: boolean - desc: - type: string - past: - type: string - parameters: - type: array - items: - type: object - properties: - name: - type: string - category: - type: integer - value: - type: string - states: - type: object - properties: - state: - type: array - items: - type: object - properties: - id: - type: integer - name: - type: string - type: - type: integer - display: - type: integer - timezone: - type: boolean - desc: - type: string - past: - type: string - parameters: - type: array - items: - type: object - properties: - name: - type: string - category: - type: integer - value: - type: string - and: - type: object - properties: - state: - type: array - items: - type: object - properties: - id: - type: integer - name: - type: string - type: - type: integer - display: - type: integer - timezone: - type: boolean - desc: - type: string - past: - type: string - functionGroup: - type: string - parameters: - type: array - items: - type: object - properties: - name: - type: string - category: - type: integer - value: - type: string - unit: - type: string - required: - - name - - category - - value - required: - - id - - name - - type - - display - - timezone - - desc - - past - - parameters - actions: + timezone: + type: boolean + desc: + type: string + past: + type: string + parameters: type: array items: type: object properties: - id: - type: integer name: type: string - type: - type: integer - display: + category: type: integer - timezone: + optional: type: boolean desc: type: string - parameters: + values: type: array items: type: object properties: - name: + id: type: string - category: - type: integer - value: + name: type: string - example: - resultCode: 0 - rules: - - id: 2367670 - name: If my door opens when I am away or it is cold and wind is strong then notify me by phone - secondName: Monitor my door - status: 1 - hidden: false - default: true - goalId: 123 - trigger: - id: 35 - name: trigger door/window opens - type: 14 - display: 14 - timezone: false - desc: opens - past: opened - parameters: - - name: deviceId - category: 5 - value: ABC123 - states: - state: - - id: 5 - name: Away state - type: 21 - display: 22 - timezone: false - desc: am away - past: were away - parameters: - - name: locationId - category: 4 - value: '3' - and: - state: - - id: 6 - name: Temperature is cold - type: 21 - display: 22 - timezone: false - desc: it is cold - past: it was cold - functionGroup: coldTemp - parameters: - - name: temp - category: 1 - value: '0' - unit: degrees C - - id: 7 - name: Wind is strong - type: 21 - display: 22 - timezone: false - desc: wind is strong - past: wind was strong - parameters: - - name: wingSpeed - category: 1 - value: '40' - actions: - - id: 14 - name: notification to phone action - type: 31 - display: 31 - timezone: false - desc: notify me by phone + required: + - id + - name + required: + - name + - category + - optional + - desc + - values + functionGroup: + type: string + required: + - id + - name + - type + - display + - timezone + - desc + - past + - parameters + actions: + type: array + items: + type: object + properties: + id: + type: integer + name: + type: string + type: + type: integer + display: + type: integer + timezone: + type: boolean + desc: + type: string + past: + type: string parameters: - - name: text - category: 10 - value: Your door opened while you were away! + type: array + items: + type: object + properties: + name: + type: string + category: + type: integer + optional: + type: boolean + desc: + type: string + values: + type: array + items: + type: object + properties: + id: + type: string + name: + type: string + selectorValue: + type: string + required: + - id + - name + - selectorValue + selectorName: + type: string + required: + - name + - category + - optional + - desc + - values + required: + - id + - name + - type + - display + - timezone + - desc + - parameters + example: + resultCode: 0 + triggers: + - id: 5 + name: schedule + type: 11 + display: 11 + timezone: true + desc: $schedule + past: $schedule + functionGroup: schedule + parameters: + - name: schedule + category: 2 + optional: false + desc: What time? + - name: timeZone + category: 3 + optional: false + desc: Is this timezone OK? + - id: 10 + name: Device offline + type: 11 + display: 13 + timezone: true + desc: goes offline + past: went offline + parameters: + - name: deviceId + category: 5 + optional: false + desc: device + values: + - id: 470FF274-8700-44AB-A273-A70691A3C140::4 + name: moss mobile 6 + - id: ea5101a8005f-10031-470 + name: Gateway + - id: 22 + name: Smart plug turned off trigger + type: 14 + display: 14 + timezone: false + desc: switches off + past: switched off + parameters: + - name: deviceId + category: 5 + optional: false + desc: smart plug + values: + - id: 470FF274-8700-44AB-A273-A70691A3C140::4 + name: moss mobile 6 + - id: 77 + name: Door open timer + type: 15 + display: 13 + timezone: false + desc: is opened for $minutes minutes + past: was opened for $minutes minutes + parameters: + - name: deviceId + category: 5 + optional: false + desc: entry sensor + values: + - id: 12345ABCDEF + name: Front Door + - name: minutes + category: 1 + optional: false + desc: How long in minutes? + value: '5' + valueType: 1 + unit: minute + minValue: '1' + maxValue: '120' + states: + - id: 9 + name: Location state + type: 21 + display: 22 + timezone: false + desc: am + past: was + parameters: + - name: locationId + category: 4 + optional: false + desc: my location + values: + - id: '5' + name: David Moss + - name: event + category: 13 + optional: false + desc: state + values: + - id: HOME + name: Home + - id: AWAY + name: Away + - id: VACATION + name: Vacation + - id: 18 + name: Device online + type: 21 + display: 23 + timezone: true + desc: is online + past: was online + functionGroup: online + parameters: + - name: deviceId + category: 5 + optional: false + desc: device + values: + - id: 470FF274-8700-44AB-A273-A70691A3C140::4 + name: moss mobile 6 + - id: ea5101a8005f-10031-470 + name: Gateway + - id: 19 + name: Device offline + type: 21 + display: 23 + timezone: true + desc: is offline + past: was offline + - id: 23 + name: Smart plug is on state + type: 21 + display: 23 + timezone: false + desc: is switched on + past: was switched on + parameters: + - name: deviceId + category: 5 + optional: false + desc: smart plug + values: + - id: 470FF274-8700-44AB-A273-A70691A3C140::4 + name: moss mobile 6 + actions: + - id: 4 + name: GP notification to phone + type: 31 + display: 31 + timezone: false + desc: send a notification to my phone + past: sent a notification to my phone + parameters: + - name: text + category: 10 + optional: false + desc: notification text + - id: 40 + name: Camera alert me with a picture + type: 33 + display: 33 + timezone: false + desc: alert me with a picture + parameters: + - name: deviceId + category: 5 + optional: false + desc: Camera + values: + - id: 470FF274-8700-44AB-A273-A70691A3C140::4 + name: moss mobile 6 + - id: ea5101a8005f-10031-470 + name: Gateway + - id: virtualpsm-6-4e7 + name: Light + - id: 41 + name: Camera point to vantage point action + type: 33 + display: 33 + timezone: false + desc: point to my '$point' vantage point + parameters: + - name: deviceId + category: 5 + values: + - id: CAMERA_ID_1 + name: Living Room Camera + - id: CAMERA_ID_2 + name: Bedroom Camera + - name: point + category: 15 + selectorName: deviceId + values: + - id: '0' + name: Front Door + selectorValue: CAMERA_ID_1 + - id: '1' + name: Front Window + selectorValue: CAMERA_ID_1 + - id: '0' + name: Bedroom Door + selectorValue: CAMERA_ID_2 + - id: '1' + name: Bedroom Window + selectorValue: CAMERA_ID_2 + + + /cloud/json/rules: + post: + summary: Create a Rule + operationId: Create a Rule + description: |- + When creating a rule, specify a single trigger, one or more states, and one or more actions, + by referencing the ID's of the triggers / states / actions that are available to the user through the GET API. - delete: - summary: Delete Rules by Criteria - operationId: Delete Rules by Criteria - description: Delete all rules matching to selection criteria. - tags: - - Rules Engine - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - - name: ruleId - in: query - description: Rule ID's. Multiple values are supported. - schema: - type: integer - - name: status - in: query - description: Rules status - schema: - type: integer - - name: deviceType - in: query - description: Delete rules containing devices of these types. Multiple values are supported. - schema: - type: integer - - name: deviceId - in: query - description: Delete rules containing these devices. Multiple values are supported. - schema: - type: string - - name: default - in: query - description: If set, delete only default or non-default rules. - schema: - type: boolean - - name: hidden - in: query - description: If set, delete only hidden or non-hidden rules. - schema: - type: boolean - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 + States are OR'd together by default, unless wrapped in an AND block. + This is to provide flexibility to the developer to implement, but we recommend only defining states inside AND blocks to keep the UI simple to understand. + If a trigger / state / action requires a parameter, the parameter must be filled out completely. - /cloud/json/rules/{ruleId}: - put: - summary: Update a Rule - operationId: Update a Rule + It is possible to save a rule that is not complete. The Care Daily AI Platform will not execute partial rules. tags: - Rules Engine security: - userApiKey: [] parameters: - - name: ruleId - in: path - description: Rule ID to update - required: true - schema: - type: integer - name: locationId in: query description: Location ID @@ -14726,227 +14436,55 @@ paths: properties: resultCode: type: integer + rule: + type: object + properties: + id: + type: integer + description: Created rule ID example: resultCode: 0 - - delete: - summary: Delete a Rule - operationId: Delete a Rule - tags: - - Rules Engine - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: ruleId - in: path - description: Rule ID to delete - required: true - schema: - type: integer - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/json/rules/{ruleId}/attrs: - put: - summary: Update a Rule Attribute - operationId: Update a Rule Attribute - description: Update the second name or status of the rule. - tags: - - Rules Engine - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: ruleId - in: path - description: Rule ID to update - required: true - schema: - type: integer - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - requestBody: - content: - application/json: - example: - rule: - name: Rule name - status: 1 - schema: - type: object - properties: rule: - type: object - properties: - name: - type: string - status: - type: integer - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - example: - resultCode: 0 - - - /cloud/json/rulesStatus/{status}: - put: - summary: Update Rules Status - operationId: Update Rules Status - description: |- - Update status of all rules matching to selection criteria. - The API returns ID's of updated rules. - tags: - - Rules Engine - security: - - userApiKey: [] - - botApiKey: [] - parameters: - - name: status - in: path - description: New rules status - required: true - schema: - type: integer - - name: locationId - in: query - description: Location ID - required: true - schema: - type: integer - - name: ruleId - in: query - description: Rule ID's to update. Multiple values are supported. - schema: - type: integer - - name: deviceType - in: query - description: Update rules containing devices of these types. Multiple values are supported. - schema: - type: integer - - name: deviceId - in: query - description: Update rules containing these devices. Multiple values are supported. - schema: - type: string - - name: default - in: query - description: If set, update only default or non-default rules. - schema: - type: boolean - - name: hidden - in: query - description: If set, update only hidden or non-hidden rules. - schema: - type: boolean - responses: - '200': - description: OK - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - ruleIds: - type: array - items: - type: integer - example: - resultCode: 0 - ruleIds: - - 123 - - 234 - - 345 - + id: 1234 - /cloud/json/servicePlans: get: - summary: Get Available Service Plans - operationId: Get Available Service Plans - description: |- - Return a list of paid service plans for sale, or having been purchased by the user. - System and organization administrators can retrieve data for other users. - - Software service plans can be subscription-based, or one-time feature buys. + summary: Get Rules + operationId: Get Rules + description: This API will allow you to filter the list of rules by criteria. tags: - - Subscriptions + - Rules Engine security: - userApiKey: [] + - botApiKey: [] parameters: - name: locationId in: query - description: Location ID, required to get data for specific location + description: Location ID + required: true schema: type: integer - - name: appName + - name: ruleId in: query - description: Retrieve service plans available for the given unique app name + description: Only return this rule schema: type: string - - name: userId - in: query - description: Used by administrators to specify another user - schema: - type: integer - - name: organizationId - in: query - description: Receive plans for another user in specific organization - schema: - type: integer - - name: deleted - in: query - description: Return deleted plans - schema: - type: boolean - - name: hiddenPrices + - name: deviceId in: query - description: Return hidden prices. It can be useful for testing new features before exposing them to public + description: Only return rules for the given device ID schema: - type: boolean - - name: plansOnly + type: string + - name: details in: query - description: Return only service plans data without checking availability + description: |- + true - Return details for this rule, including all the triggers, states, and actions that compose the rule. +
+ false - Only return the high level information about the rule, including the id, description text, + on/off status, whether the rule is a default rule, and whether the rule is hidden and not editable, default schema: type: boolean - - name: paymentType - in: query - description: Return only plans with prices of this payment type - schema: - type: integer responses: '200': - description: Service Plans + description: Rules content: application/json: schema: @@ -14954,350 +14492,502 @@ paths: properties: resultCode: type: integer - servicePlans: + rules: type: array items: type: object properties: id: type: integer - description: Service Plan ID name: type: string - description: Service Plan Name - desc: + secondName: type: string - description: Service Plan Description - deleted: + status: + type: integer + hidden: type: boolean - description: If the plan is deleted - available: + default: type: boolean - description: Whether this service plan is available to purchase - upgradableTo: - type: array - description: Service plan ID's, where this plan can be upgraded - items: - type: integer - freemium: + goalId: type: integer - description: 1 = freemium, 2 = fallback - services: - type: array - description: Services included to this plan with amounts and related resource types - items: - type: object - properties: - name: - type: string - amount: - type: integer - resourceType: - type: integer - required: - - name - - amount - - resourceType - bots: - type: array - description: Bots included to this plan with resource types - items: - type: object - properties: - bundle: - type: string - resourceType: - type: integer - prices: - type: array - items: - type: object - description: Prices and options to purchase this service - properties: - id: - type: integer - type: - type: integer - description: Subscription type - paymentType: - type: integer - description: Payment type - free: - type: boolean - description: If a limited free trial option is available - duration: - type: integer - description: Duration of the subscription in days, if this is a Non-Renewable subscription that requires the Care Daily AI Platform to expire the subscription. - gatewayId: - type: string - description: |- - Unique payment gateway product ID for the service plan, e.g. Apple Store product ID or Chargify product handle plus price handle separated by colon. - You must create an identical product identifier in your iTunes Connect account so Apple can facilitate the sale. - gatewaySandboxId: - type: string - description: Unique payment gateway sandbox product ID. Not used for Chargify. - currencySymbol: - type: string - description: Price amount currency symbol - currencyCode: - type: string - description: Price amount currency code - totalAmount: - type: string - description: Total price amount - amounts: - type: array - description: Price amounts for each item - items: - type: object - properties: - value: - type: string - desc: - type: string - taxable: - type: boolean - required: - - value - - desc - required: - - id - - type - - paymentType - - duration - - gatewayId - - currencySymbol - - currencyCode - - totalAmount - - amounts - subscriptions: + trigger: + type: object + properties: + id: + type: integer + name: + type: string + type: + type: integer + display: + type: integer + timezone: + type: boolean + desc: + type: string + past: + type: string + parameters: + type: array + items: + type: object + properties: + name: + type: string + category: + type: integer + value: + type: string + states: + type: object + properties: + state: + type: array + items: + type: object + properties: + id: + type: integer + name: + type: string + type: + type: integer + display: + type: integer + timezone: + type: boolean + desc: + type: string + past: + type: string + parameters: + type: array + items: + type: object + properties: + name: + type: string + category: + type: integer + value: + type: string + and: + type: object + properties: + state: + type: array + items: + type: object + properties: + id: + type: integer + name: + type: string + type: + type: integer + display: + type: integer + timezone: + type: boolean + desc: + type: string + past: + type: string + functionGroup: + type: string + parameters: + type: array + items: + type: object + properties: + name: + type: string + category: + type: integer + value: + type: string + unit: + type: string + required: + - name + - category + - value + required: + - id + - name + - type + - display + - timezone + - desc + - past + - parameters + actions: type: array - description: Existing service plans on this location items: type: object properties: - userPlanId: - type: integer - description: User service plan ID - startDate: - type: string - description: Start date of the plan - startDateMs: - type: integer - endDate: - type: string - description: End date of the plan - endDateMs: + id: type: integer - issueDate: + name: type: string - description: Issue date of the plan - issueDateMs: - type: integer - free: - type: boolean - description: If it is a free trial type: type: integer - description: Subscription type - paymentType: - type: integer - description: Payment type - organizationId: - type: integer - description: Organization purchased this plan for the location - gatewayId: - type: string - description: Payment gateway product ID of this plan - priceId: + display: type: integer - description: Price ID - subscriptionId: - type: string - description: Payment gateway subscription ID or original transaction ID - transactionId: + timezone: + type: boolean + desc: type: string - description: The last transaction ID - duration: - type: integer - description: Duration of the plan in days, if this is a Non-Renewable subscription that requires the Care Daily AI Platform to expire the plan. - required: - - userPlanId - - startDate - - startDateMs - - endDate - - endDateMs - - type - - paymentType - - gatewayId - - priceId - - subscriptionId - - transactionId - required: - - id - - name - - desc - - available - - services - - prices + parameters: + type: array + items: + type: object + properties: + name: + type: string + category: + type: integer + value: + type: string example: resultCode: 0 - servicePlans: - - id: 3 - name: Pro Video - desc: Pro Video service and 5 GB disk space - deleted: false - available: false - upgradableTo: - - 4 - services: - - name: ProVideo - amount: 1 - resourceType: 1 - - name: DeviceFileSpace - amount: 5368709120 - resourceType: 1 - bots: - - bundle: com.ppc.security - resourceType: 1 - prices: - - id: 1 - type: 1 - paymentType: 0 - free: true - duration: 30 - - id: 2 - type: 1 - paymentType: 1 - gatewayId: com.peoplepowerco.presencepro_1w - duration: 7 - currencySymbol: $ - currencyCode: USD - totalAmount: '19.99' - amounts: - - value: '9.99' - desc: basic service - taxable: false - - value: '10' - desc: pro service - taxable: true - - id: 3 - type: 3 - paymentType: 2 - gatewayId: P-1234567 - currencySymbol: $ - currencyCode: USD - totalAmount: '19.99' - amounts: - - value: '9.99' - desc: basic service - taxable: false - - value: '10' - desc: pro service - taxable: true - - id: 4 - type: 4 - paymentType: 1 - gatewayId: com.peoplepowerco.presencepro_1year - subscriptions: - - userPlanId: 12344 - startDate: '2013-12-13T00:00:00-05:00' - startDateMs: 1386910800000 - endDate: '2030-01-01T00:00:00-05:00' - endDateMs: 1893474000000 - free: false - type: 1 - paymentType: 0 - organizationId: 123 - - userPlanId: 12345 - startDate: '2013-12-13T00:00:00-05:00' - startDateMs: 1386910800000 - endDate: '2030-01-01T00:00:00-05:00' - endDateMs: 1893474000000 - type: 3 - paymentType: 1 - gatewayId: com.peoplepowerco.presencepro_1m - priceId: 1 - subscriptionId: abc123 - transactionId: '1234567' - - userPlanId: 12346 - startDate: '2013-12-13T00:00:00-05:00' - startDateMs: 1386910800000 - endDate: '2030-01-01T00:00:00-05:00' - endDateMs: 1893474000000 - type: 1 - paymentType: 3 - gatewayId: BTPlanID - priceId: 2 - duration: 7 - subscriptionId: abc124 - transactionId: '78906543' - - id: 4 - name: Pro Video disk space - desc: Extra 5 GB disk space for Pro Video users - available: true - services: - - name: DeviceFileSpace - amount: 5368709120 - resourceType: 1 - prices: - - id: 11 - type: 3 - paymentType: 1 - gatewayId: com.peoplepowerco.presencedisk_1m - - id: 12 - type: 4 - paymentType: 1 - gatewayId: com.peoplepowerco.presencedisk_1year - - - /cloud/json/userServicePlans: - get: - summary: Get Location Service Plans - operationId: Get Location Service Plans - description: |- - This API returns all service plans on specific location or purchased by a user or manually assigned to him. + rules: + - id: 2367670 + name: If my door opens when I am away or it is cold and wind is strong then notify me by phone + secondName: Monitor my door + status: 1 + hidden: false + default: true + goalId: 123 + trigger: + id: 35 + name: trigger door/window opens + type: 14 + display: 14 + timezone: false + desc: opens + past: opened + parameters: + - name: deviceId + category: 5 + value: ABC123 + states: + state: + - id: 5 + name: Away state + type: 21 + display: 22 + timezone: false + desc: am away + past: were away + parameters: + - name: locationId + category: 4 + value: '3' + and: + state: + - id: 6 + name: Temperature is cold + type: 21 + display: 22 + timezone: false + desc: it is cold + past: it was cold + functionGroup: coldTemp + parameters: + - name: temp + category: 1 + value: '0' + unit: degrees C + - id: 7 + name: Wind is strong + type: 21 + display: 22 + timezone: false + desc: wind is strong + past: wind was strong + parameters: + - name: wingSpeed + category: 1 + value: '40' + actions: + - id: 14 + name: notification to phone action + type: 31 + display: 31 + timezone: false + desc: notify me by phone + parameters: + - name: text + category: 10 + value: Your door opened while you were away! - Either `locationId` or `userId` parameters must be used. + delete: + summary: Delete Rules by Criteria + operationId: Delete Rules by Criteria + description: Delete all rules matching to selection criteria. tags: - - Subscriptions + - Rules Engine security: - userApiKey: [] + - botApiKey: [] parameters: - name: locationId in: query - description: Get plan on this location + description: Location ID + required: true + schema: + type: integer + - name: ruleId + in: query + description: Rule ID's. Multiple values are supported. schema: type: integer - name: status in: query - description: |- - Service plan status filter -
0 - active -
1 - expired or canceled -
2 - paused -
-1 - initial -
Multiple values supported. + description: Rules status schema: type: integer - - name: userPlanId + - name: deviceType in: query - description: Get specific service plan by ID + description: Delete rules containing devices of these types. Multiple values are supported. schema: type: integer - - name: getCard + - name: deviceId + in: query + description: Delete rules containing these devices. Multiple values are supported. + schema: + type: string + - name: default in: query - description: Retrieve payment card information from the payment provider. It can be slow! + description: If set, delete only default or non-default rules. schema: type: boolean - - name: userId + - name: hidden in: query - description: Get plan by this user. Used by organization administrators. + description: If set, delete only hidden or non-hidden rules. + schema: + type: boolean + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 + + + /cloud/json/rules/{ruleId}: + put: + summary: Update a Rule + operationId: Update a Rule + tags: + - Rules Engine + security: + - userApiKey: [] + parameters: + - name: ruleId + in: path + description: Rule ID to update + required: true + schema: + type: integer + - name: locationId + in: query + description: Location ID + required: true schema: type: integer + requestBody: + content: + application/json: + example: + rule: + status: 1 + timeZone: US/Pacific + hidden: false + trigger: + id: 121 + parameter: + - name: schedule + value: 0 30 16 * * ? + - name: locationId + value: '123' + calendar: + - include: false + startTime: 3600 + endTime: 4200 + - include: false + daysOfWeek: 65 + states: + state: + - id: 125 + parameter: + - name: temp + value: '25' + - id: 129 + parameter: + - name: event + value: home + and: + - state: + - id: 123 + parameter: + - name: deviceId + value: ABC123 + - id: 124 + parameter: + - name: locationId + value: '125' + - state: + - id: 130 + parameter: + - name: deviceId + value: ABC123 + - id: 131 + parameter: + - name: locationId + value: '125' + actions: + action: + - id: 126 + - id: 127 + parameter: + - name: deviceId + value: AC123 + - name: index + value: '0' + schema: + type: object + properties: + rule: + type: object + properties: + status: + type: integer + timeZone: + type: string + hidden: + type: boolean + trigger: + type: object + properties: + id: + type: integer + parameter: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + required: + - name + - value + calendar: + type: array + items: + type: object + properties: + include: + type: boolean + startTime: + type: integer + endTime: + type: integer + daysOfWeek: + type: integer + required: + - include + states: + type: object + properties: + state: + type: array + items: + type: object + properties: + id: + type: integer + parameter: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + required: + - name + - value + required: + - id + - parameter + and: + type: array + items: + type: object + properties: + state: + type: array + items: + type: object + properties: + id: + type: integer + parameter: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + required: + - name + - value + required: + - id + - parameter + required: + - state + actions: + type: object + properties: + action: + type: array + items: + type: object + properties: + id: + type: integer + parameter: + type: array + items: + type: object + properties: + name: + type: string + value: + type: string + required: + - name + - value + required: + - id responses: '200': - description: Service Plans + description: OK content: application/json: schema: @@ -15305,243 +14995,30 @@ paths: properties: resultCode: type: integer - subscriptions: - type: array - items: - type: object - properties: - userPlanId: - type: integer - description: User service plan ID - plan: - type: object - description: Service Plan - properties: - id: - type: integer - name: - type: string - desc: - type: string - updatePlan: - type: object - properties: - id: - type: integer - name: - type: string - desc: - type: string - locationId: - type: integer - userId: - type: integer - type: - type: integer - description: Subscription Type - paymentType: - type: integer - status: - type: integer - issueDate: - type: string - issueDateMs: - type: integer - startDate: - type: string - startDateMs: - type: integer - endDate: - type: string - endDateMs: - type: integer - free: - type: boolean - gatewayId: - type: string - priceId: - type: integer - subscriptionId: - type: string - transactionId: - type: string - sandbox: - type: boolean - appName: - type: string - cardMaskedNumber: - type: string - description: Masked payment card number - cardExpirationDate: - type: string - services: - type: array - items: - type: object - properties: - name: - type: string - amount: - type: integer - resourceType: - type: integer - required: - - name - - amount - - resourceType - upgradableTo: - type: array - items: - type: integer - organizationId: - type: integer - duration: - type: integer - cancelled: - type: boolean - cancelTransactionId: - type: string - cancelDate: - type: string - cancelDateMs: - type: integer - required: - - userPlanId - - plan - - locationId - - userId - - type - - paymentType - - status - - issueDate - - issueDateMs - - startDate - - startDateMs - - endDate - - endDateMs - - services example: resultCode: 0 - subscriptions: - - userPlanId: 12344 - plan: - id: 3 - name: Pro Video - desc: Pro Video service and 2 GB disk space - updatePlan: - id: 4 - name: Super Pro Video - desc: Pro Video service and 20 GB disk space - locationId: 123 - userId: 456 - type: 3 - paymentType: 1 - status: 0 - issueDate: '2013-09-13T00:00:00-05:00' - issueDateMs: 1386910800000 - startDate: '2013-12-13T00:00:00-05:00' - startDateMs: 1386910800000 - endDate: '2014-01-03T00:00:00-05:00' - endDateMs: 1893474000000 - free: false - gatewayId: com.peoplepowerco.presencepro_1m - priceId: 10 - subscriptionId: abc123 - transactionId: '1234567' - sandbox: false - appName: presence - cardMaskedNumber: 1234********5678 - cardExpirationDate: '2017-07-08' - services: - - name: DeviceFileSpace - amount: 7 - resourceType: 1 - upgradableTo: - - 5 - - userPlanId: 12345 - plan: - id: 4 - name: Pro Security - desc: Pro Home Security services - locationId: 123 - userId: 456 - type: 1 - paymentType: 0 - status: 1 - issueDate: '2013-12-13T00:00:00-05:00' - issueDateMs: 1386910800000 - startDate: '2013-12-13T00:00:00-05:00' - startDateMs: 1386910800000 - endDate: '2016-12-13T00:00:00-05:00' - endDateMs: 1893474000000 - organizationId: 123 - duration: 1000 - cancelled: true - cancelTransactionId: tr12345 - cancelDate: '2014-01-03T00:00:00-05:00' - cancelDateMs: 1893474000000 - services: - - name: Family - amount: 1 - resourceType: 1 - - - /cloud/json/userServicePlans/{servicePlanId}: - post: - summary: Assign Service Plan to Locations - operationId: Assign Service Plan to Locations - description: |- - This API can be called by any user to assign free services. - An administrator with a corresponding privilege level must provide a list of locations where to assign the service plan. - In multiple locations assignment result codes are returned for each of them. - User IDs are optional, but if set, their access to locations will be verified. + delete: + summary: Delete a Rule + operationId: Delete a Rule tags: - - Subscriptions + - Rules Engine security: - userApiKey: [] + - botApiKey: [] parameters: - - name: servicePlanId + - name: ruleId in: path - description: The Service Plan ID to assign + description: Rule ID to delete required: true schema: type: integer - - name: organizationId - in: query - description: Organization ID. Required if called by an organization administrator. - schema: - type: integer - - name: endDate - in: query - description: The end date of the service plan - schema: - type: string - name: locationId in: query - description: Location ID to assign the service plan + description: Location ID + required: true schema: type: integer - requestBody: - content: - application/json: - schema: - type: object - properties: - locations: - type: array - description: Location and user IDs to assign the service plan - items: - type: object - properties: - locationId: - type: integer - userId: - type: integer - example: - locations: - - locationId: 123 - userId: 456 responses: '200': description: OK @@ -15552,47 +15029,50 @@ paths: properties: resultCode: type: integer - results: - type: array - description: Result codes for assigning the plan to each location ID from the request body - items: - type: object - properties: - locationId: - type: integer - resultCode: - type: integer example: resultCode: 0 - results: - - locationId: 123 - resultCode: 0 - delete: - summary: Cancel Service Plan - operationId: Cancel Service Plan - description: Cancel assigned service plan. + + /cloud/json/rules/{ruleId}/attrs: + put: + summary: Update a Rule Attribute + operationId: Update a Rule Attribute + description: Update the second name or status of the rule. tags: - - Subscriptions + - Rules Engine security: - userApiKey: [] + - botApiKey: [] parameters: - - name: servicePlanId + - name: ruleId in: path - description: The User service plan ID to cancel + description: Rule ID to update required: true schema: type: integer - name: locationId in: query - description: Location ID to cancel the service plan - schema: - type: integer - - name: organizationId - in: query - description: Organization ID. Required if called by an organization administrator. + description: Location ID + required: true schema: type: integer + requestBody: + content: + application/json: + example: + rule: + name: Rule name + status: 1 + schema: + type: object + properties: + rule: + type: object + properties: + name: + type: string + status: + type: integer responses: '200': description: OK @@ -15607,19 +15087,22 @@ paths: resultCode: 0 - /cloud/json/userServicePlanTransactions/{userServicePlanId}: - get: - summary: Get Transactions - operationId: Get Transactions - description: This API returns all payment transactions for specific user service plan. + /cloud/json/rulesStatus/{status}: + put: + summary: Update Rules Status + operationId: Update Rules Status + description: |- + Update status of all rules matching to selection criteria. + The API returns ID's of updated rules. tags: - - Subscriptions + - Rules Engine security: - userApiKey: [] + - botApiKey: [] parameters: - - name: userServicePlanId + - name: status in: path - description: User service plan ID + description: New rules status required: true schema: type: integer @@ -15629,14 +15112,34 @@ paths: required: true schema: type: integer - - name: upgrade + - name: ruleId in: query - description: Return only transactions, which caused service plan change + description: Rule ID's to update. Multiple values are supported. + schema: + type: integer + - name: deviceType + in: query + description: Update rules containing devices of these types. Multiple values are supported. + schema: + type: integer + - name: deviceId + in: query + description: Update rules containing these devices. Multiple values are supported. + schema: + type: string + - name: default + in: query + description: If set, update only default or non-default rules. + schema: + type: boolean + - name: hidden + in: query + description: If set, update only hidden or non-hidden rules. schema: type: boolean responses: '200': - description: Transactions + description: OK content: application/json: schema: @@ -15644,97 +15147,27 @@ paths: properties: resultCode: type: integer - transactions: + ruleIds: type: array items: - type: object - properties: - transactionId: - type: string - gatewayId: - type: string - status: - type: integer - issueDate: - type: string - issueDateMs: - type: integer - startDate: - type: string - startDateMs: - type: integer - endDate: - type: string - endDateMs: - type: integer - amount: - type: integer - priceId: - type: integer - prevPriceId: - type: integer - plan: - type: object - properties: - id: - type: integer - name: - type: string - desc: - type: string - prevPlan: - type: object - properties: - id: - type: integer - name: - type: string - desc: - type: string + type: integer example: resultCode: 0 - transactions: - - transactionId: abc123 - gatewayId: com.peoplepowerco.presencepro_1m - status: 0 - issueDate: '2013-09-13T00:00:00-05:00' - issueDateMs: 1386910800000 - startDate: '2013-12-13T00:00:00-05:00' - startDateMs: 1386910800000 - endDate: '2014-01-03T00:00:00-05:00' - endDateMs: 1893474000000 - amount: 9.99 - priceId: 10 - prevPriceId: 11 - plan: - id: 3 - name: Pro Video - desc: Pro Video service and 2 GB disk space - prevPlan: - id: 2 - name: Free Video - desc: Free Video service + ruleIds: + - 123 + - 234 + - 345 - /cloud/json/receipt/apple: - post: - summary: Apple Purchase - operationId: Apple Purchase + /cloud/json/servicePlans: + get: + summary: Get Available Service Plans + operationId: Get Available Service Plans description: |- - The Care Daily AI Platform supports Apple's Auto-renewable subscriptions - as well as Non-Renewing subscriptions with custom limits on durations. - Please see https://developer.apple.com/in-app-purchase/ for more details. - - When making a purchase through the Apple App Store, the app will hand over control to Apple to handle the transaction. - When the transaction is complete, it is the app's responsibility to capture the authenticated receipt from Apple and reliably pass the receipt to the Care Daily AI Platform. - The Care Daily AI Platform will validate the receipt by calling the payment provider's server, and then securely apply the purchase to the user's account. + Return a list of paid service plans for sale, or having been purchased by the user. + System and organization administrators can retrieve data for other users. - This API will return a result code: - * *0 = Success* - * *6 = Object Not Found*, the receipt is not found on the Apple Store - * *7 = Access Denied*, the receipt is already submitted by a different user - * *8 = Wrong Parameter Value*, The receipt is invalid or expired - * *26 = Duplicate Entry*, The receipt is already submitted by the same user + Software service plans can be subscription-based, or one-time feature buys. tags: - Subscriptions security: @@ -15742,18 +15175,47 @@ paths: parameters: - name: locationId in: query - description: Location ID - required: true + description: Location ID, required to get data for specific location schema: type: integer - name: appName in: query - description: Unique app name that is making the purchase + description: Retrieve service plans available for the given unique app name schema: type: string + - name: userId + in: query + description: Used by administrators to specify another user + schema: + type: integer + - name: organizationId + in: query + description: Receive plans for another user in specific organization + schema: + type: integer + - name: deleted + in: query + description: Return deleted plans + schema: + type: boolean + - name: hiddenPrices + in: query + description: Return hidden prices. It can be useful for testing new features before exposing them to public + schema: + type: boolean + - name: plansOnly + in: query + description: Return only service plans data without checking availability + schema: + type: boolean + - name: paymentType + in: query + description: Return only plans with prices of this payment type + schema: + type: integer responses: '200': - description: OK + description: Service Plans content: application/json: schema: @@ -15761,70 +15223,336 @@ paths: properties: resultCode: type: integer + servicePlans: + type: array + items: + type: object + properties: + id: + type: integer + description: Service Plan ID + name: + type: string + description: Service Plan Name + desc: + type: string + description: Service Plan Description + deleted: + type: boolean + description: If the plan is deleted + available: + type: boolean + description: Whether this service plan is available to purchase + upgradableTo: + type: array + description: Service plan ID's, where this plan can be upgraded + items: + type: integer + freemium: + type: integer + description: 1 = freemium, 2 = fallback + services: + type: array + description: Services included to this plan with amounts and related resource types + items: + type: object + properties: + name: + type: string + amount: + type: integer + required: + - name + - amount + bots: + type: array + description: Bots included to this plan with resource types + items: + type: object + properties: + bundle: + type: string + prices: + type: array + items: + type: object + description: Prices and options to purchase this service + properties: + id: + type: integer + type: + type: integer + description: Subscription type + paymentType: + type: integer + description: Payment type + free: + type: boolean + description: If a limited free trial option is available + duration: + type: integer + description: Duration of the subscription in days, if this is a Non-Renewable subscription that requires the Care Daily AI Platform to expire the subscription. + gatewayId: + type: string + description: |- + Unique payment gateway product ID for the service plan, e.g. Apple Store product ID or Chargify product handle plus price handle separated by colon. + You must create an identical product identifier in your iTunes Connect account so Apple can facilitate the sale. + gatewaySandboxId: + type: string + description: Unique payment gateway sandbox product ID. Not used for Chargify. + currencySymbol: + type: string + description: Price amount currency symbol + currencyCode: + type: string + description: Price amount currency code + totalAmount: + type: string + description: Total price amount + amounts: + type: array + description: Price amounts for each item + items: + type: object + properties: + value: + type: string + desc: + type: string + taxable: + type: boolean + required: + - value + - desc + required: + - id + - type + - paymentType + - duration + - gatewayId + - currencySymbol + - currencyCode + - totalAmount + - amounts + subscriptions: + type: array + description: Existing service plans on this location + items: + type: object + properties: + userPlanId: + type: integer + description: User service plan ID + startDate: + type: string + description: Start date of the plan + startDateMs: + type: integer + endDate: + type: string + description: End date of the plan + endDateMs: + type: integer + issueDate: + type: string + description: Issue date of the plan + issueDateMs: + type: integer + free: + type: boolean + description: If it is a free trial + type: + type: integer + description: Subscription type + paymentType: + type: integer + description: Payment type + organizationId: + type: integer + description: Organization purchased this plan for the location + gatewayId: + type: string + description: Payment gateway product ID of this plan + priceId: + type: integer + description: Price ID + subscriptionId: + type: string + description: Payment gateway subscription ID or original transaction ID + transactionId: + type: string + description: The last transaction ID + duration: + type: integer + description: Duration of the plan in days, if this is a Non-Renewable subscription that requires the Care Daily AI Platform to expire the plan. + required: + - userPlanId + - startDate + - startDateMs + - endDate + - endDateMs + - type + - paymentType + - gatewayId + - priceId + - subscriptionId + - transactionId + required: + - id + - name + - desc + - available + - services + - prices example: resultCode: 0 + servicePlans: + - id: 3 + name: Pro Video + desc: Pro Video service and 5 GB disk space + deleted: false + available: false + upgradableTo: + - 4 + services: + - name: ProVideo + amount: 1 + - name: DeviceFileSpace + amount: 5368709120 + bots: + - bundle: com.ppc.security + prices: + - id: 1 + type: 1 + paymentType: 0 + free: true + duration: 30 + - id: 2 + type: 1 + paymentType: 1 + gatewayId: com.peoplepowerco.presencepro_1w + duration: 7 + currencySymbol: $ + currencyCode: USD + totalAmount: '19.99' + amounts: + - value: '9.99' + desc: basic service + taxable: false + - value: '10' + desc: pro service + taxable: true + - id: 3 + type: 3 + paymentType: 2 + gatewayId: P-1234567 + currencySymbol: $ + currencyCode: USD + totalAmount: '19.99' + amounts: + - value: '9.99' + desc: basic service + taxable: false + - value: '10' + desc: pro service + taxable: true + - id: 4 + type: 4 + paymentType: 1 + gatewayId: com.peoplepowerco.presencepro_1year + subscriptions: + - userPlanId: 12344 + startDate: '2013-12-13T00:00:00-05:00' + startDateMs: 1386910800000 + endDate: '2030-01-01T00:00:00-05:00' + endDateMs: 1893474000000 + free: false + type: 1 + paymentType: 0 + organizationId: 123 + - userPlanId: 12345 + startDate: '2013-12-13T00:00:00-05:00' + startDateMs: 1386910800000 + endDate: '2030-01-01T00:00:00-05:00' + endDateMs: 1893474000000 + type: 3 + paymentType: 1 + gatewayId: com.peoplepowerco.presencepro_1m + priceId: 1 + subscriptionId: abc123 + transactionId: '1234567' + - userPlanId: 12346 + startDate: '2013-12-13T00:00:00-05:00' + startDateMs: 1386910800000 + endDate: '2030-01-01T00:00:00-05:00' + endDateMs: 1893474000000 + type: 1 + paymentType: 3 + gatewayId: BTPlanID + priceId: 2 + duration: 7 + subscriptionId: abc124 + transactionId: '78906543' + - id: 4 + name: Pro Video disk space + desc: Extra 5 GB disk space for Pro Video users + available: true + services: + - name: DeviceFileSpace + amount: 5368709120 + prices: + - id: 11 + type: 3 + paymentType: 1 + gatewayId: com.peoplepowerco.presencedisk_1m + - id: 12 + type: 4 + paymentType: 1 + gatewayId: com.peoplepowerco.presencedisk_1year - /cloud/json/callCenter: - get: - summary: Get Call Center - operationId: Get Call Center - description: |- - Retrieve call center service statuses, - if the service is available and if the registration in the third party application has been completed. - - If the service is available, but the registration has not been completed yet, - then the Care Daily AI Platform does not have enough information to do it. - - Call center registration can have following statuses: - - | Value | Status | Description | - | :---: | ------ | ----------- | - | 0 | Unavailable | The service never purchased | - | 1 | Available | The service purchased, but the user does not have enough information for registration | - | 2 | Registration pending | The registration process has not been completed yet | - | 3 | Registered | Registration completed | - | 4 | Cancellation pending | The cancellation has not been completed yet | - | 5 | Canceled | Cancellation completed | - - To complete the call center registration the user has to submit - own name, phone number and address using the update user info API and a list of emergency contacts. - The complete list of missing fields is returned. - - Also, this API returns an array of emergency contacts including the first and the last name, the phone number of the person in the order, how they have to be contacted. - - The alert status with the alert date is returned in a case of an emergency situation. It can have following values: - - | Value | Status | Description | - | :---: | ------ | ----------- | - | 0 | | An alert never raised | - | 1 | Raised | An alert raised, but the call center not contacted yet | - | 3 | Reported | The alert reported to the call center | - - A call center account can be temporaty set to a test mode or scheduled to be on test in the future. - - | Test Status | Description | - | :---------: | ----------- | - | 1 | Test pending | - | 2 | Active now or scheduled | - | 3 | Cancel test pending | - | 4 | Off | + /cloud/json/userServicePlans: + get: + summary: Get Location Service Plans + operationId: Get Location Service Plans + description: |- + This API returns all service plans on specific location or purchased by a user or manually assigned to him. - Third-party OAuth client supported. + Either `locationId` or `userId` parameters must be used. tags: - - Professional Monitoring + - Subscriptions security: - userApiKey: [] parameters: - name: locationId in: query - description: Location ID - required: true + description: Get plan on this location + schema: + type: integer + - name: status + in: query + description: |- + Service plan status filter +
0 - active +
1 - expired or canceled +
2 - paused +
-1 - initial +
Multiple values supported. + schema: + type: integer + - name: userPlanId + in: query + description: Get specific service plan by ID + schema: + type: integer + - name: userId + in: query + description: Get plan by this user. Used by organization administrators. schema: type: integer responses: '200': - description: Call Center Service + description: Service Plans content: application/json: schema: @@ -15832,201 +15560,233 @@ paths: properties: resultCode: type: integer - callCenter: - type: object - properties: - status: - type: integer - description: Service status - code: - type: string - description: External account code - userId: - type: integer - description: Service user's ID - missingFields: - type: array - description: Data fields required for account registration - items: - type: string - contacts: - type: array - description: User contacts to call in case of emergency - items: + subscriptions: + type: array + items: + type: object + properties: + userPlanId: + type: integer + description: User service plan ID + plan: type: object + description: Service Plan properties: - userId: + id: type: integer - description: Existing user's ID, if provided all details will be selected from the user's account - firstName: - type: string - description: First name of a contact not registered in the system - lastName: + name: type: string - description: Last name of a contact not registered in the system - phone: + desc: type: string - description: Phone number of a contact not registered in the system - phoneType: - type: integer - description: Phone type of a contact not registered in the system - ecv: - type: boolean - description: |- - Contact before bispatch, a value indicating whether the contact will be contacted before attempting to contact dispatch. Enhanced Call Verification. - True by default. - codeword: - type: string - description: Codewords - notDispatch: - type: boolean - description: Set the account dispatch type to "do not dispatch" - permit: - type: string - description: Permit number - alertStatus: - type: integer - description: Alert status - alertDate: - type: string - description: The last alert date - alertDateMs: - type: integer - alertStatusDate: - type: string - alertStatusDateMs: - type: integer - tests: - type: array - description: Test periods - items: + updatePlan: type: object properties: - testId: - type: integer - status: - type: integer - startDate: - type: string - startDateMs: + id: type: integer - endDate: + name: type: string - endDateMs: - type: integer - comment: + desc: type: string - userId: - type: integer - externalTestId: - type: integer - example: - resultCode: 0 - callCenter: - status: 1 - code: A12345 - userId: 123 - missingFields: - - user.firstName - - user.phone - - location.addrStreet1 - contacts: - - userId: 123 - firstName: Laura - lastName: Secord - phone: '1232686353' - phoneType: 1 - ecv: true - codeword: pass phrase - notDispatch: false - permit: '1234567890' - alertStatus: 3 - alertDate: '2015-09-01T18:00:00Z' - alertDateMs: 1441130400000 - alertStatusDate: '2015-09-01T18:00:30Z' - alertStatusDateMs: 1441130430000 - tests: - - testId: 123 - status: 2 - startDate: '2015-09-01T18:00:30Z' - startDateMs: 1441130430000 - endDate: '2015-09-01T19:00:30Z' - endDateMs: 1441134400000 - comment: One hour test - userId: 456 - externalTestId: 789 + locationId: + type: integer + userId: + type: integer + type: + type: integer + description: Subscription Type + paymentType: + type: integer + status: + type: integer + issueDate: + type: string + issueDateMs: + type: integer + startDate: + type: string + startDateMs: + type: integer + endDate: + type: string + endDateMs: + type: integer + free: + type: boolean + gatewayId: + type: string + priceId: + type: integer + subscriptionId: + type: string + transactionId: + type: string + sandbox: + type: boolean + services: + type: array + items: + type: object + properties: + name: + type: string + amount: + type: integer + required: + - name + - amount + upgradableTo: + type: array + items: + type: integer + organizationId: + type: integer + duration: + type: integer + cancelled: + type: boolean + cancelTransactionId: + type: string + cancelDate: + type: string + cancelDateMs: + type: integer + required: + - userPlanId + - plan + - locationId + - userId + - type + - paymentType + - status + - issueDate + - issueDateMs + - startDate + - startDateMs + - endDate + - endDateMs + - services + example: + resultCode: 0 + subscriptions: + - userPlanId: 12344 + plan: + id: 3 + name: Pro Video + desc: Pro Video service and 2 GB disk space + updatePlan: + id: 4 + name: Super Pro Video + desc: Pro Video service and 20 GB disk space + locationId: 123 + userId: 456 + type: 3 + paymentType: 1 + status: 0 + issueDate: '2013-09-13T00:00:00-05:00' + issueDateMs: 1386910800000 + startDate: '2013-12-13T00:00:00-05:00' + startDateMs: 1386910800000 + endDate: '2014-01-03T00:00:00-05:00' + endDateMs: 1893474000000 + free: false + gatewayId: com.peoplepowerco.presencepro_1m + priceId: 10 + subscriptionId: abc123 + transactionId: '1234567' + sandbox: false + appName: presence + cardMaskedNumber: 1234********5678 + cardExpirationDate: '2017-07-08' + services: + - name: DeviceFileSpace + amount: 7 + upgradableTo: + - 5 + - userPlanId: 12345 + plan: + id: 4 + name: Pro Security + desc: Pro Home Security services + locationId: 123 + userId: 456 + type: 1 + paymentType: 0 + status: 1 + issueDate: '2013-12-13T00:00:00-05:00' + issueDateMs: 1386910800000 + startDate: '2013-12-13T00:00:00-05:00' + startDateMs: 1386910800000 + endDate: '2016-12-13T00:00:00-05:00' + endDateMs: 1893474000000 + organizationId: 123 + duration: 1000 + cancelled: true + cancelTransactionId: tr12345 + cancelDate: '2014-01-03T00:00:00-05:00' + cancelDateMs: 1893474000000 + services: + - name: Family + amount: 1 - put: - summary: Update Call Center - operationId: Update Call Center + + /cloud/json/userServicePlans/{servicePlanId}: + post: + summary: Assign Service Plan to Locations + operationId: Assign Service Plan to Locations description: |- - Update user's call center record. - The API can raise an alert by setting the alert status. + This API can be called by any user to assign free services. - If the new alert status is not provided, the API overwrites the call center contacts information, codeword, permit or location owner user ID. - Submitting null or an empty contacts array will not affect existing contacts data. + An administrator with a corresponding privilege level must provide a list of locations where to assign the service plan. + In multiple locations assignment result codes are returned for each of them. + User IDs are optional, but if set, their access to locations will be verified. tags: - - Professional Monitoring + - Subscriptions security: - userApiKey: [] parameters: + - name: servicePlanId + in: path + description: The Service Plan ID to assign + required: true + schema: + type: integer + - name: organizationId + in: query + description: Organization ID. Required if called by an organization administrator. + schema: + type: integer + - name: endDate + in: query + description: The end date of the service plan + schema: + type: string - name: locationId in: query - description: Location ID - required: true + description: Location ID to assign the service plan by an end-user schema: type: integer requestBody: content: application/json: - example: - callCenter: - alertStatus: 1 - userId: 123 - contacts: - - userId: 123 - firstName: Laura - lastName: Secord - phone: '1232686353' - phoneType: 1 - ecv: true - codeword: secret - notDispatch: true - permit: '1234567890' schema: type: object properties: - callCenter: - type: object - properties: - alertStatus: - type: integer - description: To raise an alert set it to 1 (raised) - userId: - type: integer - contacts: - type: array - items: - type: object - properties: - userId: - type: integer - firstName: - type: string - lastName: - type: string - phone: - type: string - phoneType: - type: integer - ecv: - type: boolean - codeword: - type: string - notDispatch: - type: boolean - permit: - type: string + locations: + type: array + description: Location and user IDs to assign the service plan by an administrator + items: + type: object + properties: + locationId: + type: integer + userId: + type: integer + required: + - locationId + example: + locations: + - locationId: 123 + userId: 456 responses: '200': description: OK @@ -16037,37 +15797,45 @@ paths: properties: resultCode: type: integer - callCenter: - type: object - properties: - status: - type: integer - missingFields: - type: array - items: - type: string + results: + type: array + description: Result codes for assigning the plan to each location ID from the request body + items: + type: object + properties: + locationId: + type: integer + resultCode: + type: integer example: resultCode: 0 - callCenter: - status: 1 - missingFields: - - user.firstName - - user.phone - - location.addrStreet1 + results: + - locationId: 123 + resultCode: 0 delete: - summary: Cancel Call Center Account - operationId: Cancel Call Center - description: Update user's call center record status to available and delete contacts. + summary: Cancel Service Plan + operationId: Cancel Service Plan + description: Cancel assigned service plan. tags: - - Professional Monitoring + - Subscriptions security: - userApiKey: [] parameters: + - name: servicePlanId + in: path + description: The User service plan ID to cancel + required: true + schema: + type: integer - name: locationId in: query - description: Location ID - required: true + description: Location ID to cancel the service plan + schema: + type: integer + - name: organizationId + in: query + description: Organization ID. Required if called by an organization administrator. schema: type: integer responses: @@ -16083,41 +15851,37 @@ paths: example: resultCode: 0 - /cloud/json/callCenterTest: - post: - summary: Create Call Center Test - operationId: Create Call Center Test - description: Create a test period for a call center account from optional `startDate` to `endDate`. + + /cloud/json/userServicePlanTransactions/{userServicePlanId}: + get: + summary: Get Transactions + operationId: Get Transactions + description: This API returns all payment transactions for specific user service plan. tags: - - Professional Monitoring + - Subscriptions security: - userApiKey: [] parameters: + - name: userServicePlanId + in: path + description: User service plan ID + required: true + schema: + type: integer - name: locationId in: query description: Location ID required: true schema: type: integer - requestBody: - content: - application/json: - example: - startDate: '2024-10-18T12:00:00Z' - endDate: '2024-10-18T13:00:00Z' - comment: One hour test comment - schema: - type: object - properties: - startDate: - type: string - endDate: - type: string - comment: - type: string + - name: upgrade + in: query + description: Return only transactions, which caused service plan change + schema: + type: boolean responses: '200': - description: OK + description: Transactions content: application/json: schema: @@ -16125,15 +15889,99 @@ paths: properties: resultCode: type: integer + transactions: + type: array + items: + type: object + properties: + transactionId: + type: string + gatewayId: + type: string + status: + type: integer + issueDate: + type: string + issueDateMs: + type: integer + startDate: + type: string + startDateMs: + type: integer + endDate: + type: string + endDateMs: + type: integer + amount: + type: integer + priceId: + type: integer + prevPriceId: + type: integer + plan: + type: object + properties: + id: + type: integer + name: + type: string + desc: + type: string + prevPlan: + type: object + properties: + id: + type: integer + name: + type: string + desc: + type: string example: resultCode: 0 + transactions: + - transactionId: abc123 + gatewayId: com.peoplepowerco.presencepro_1m + status: 0 + issueDate: '2013-09-13T00:00:00-05:00' + issueDateMs: 1386910800000 + startDate: '2013-12-13T00:00:00-05:00' + startDateMs: 1386910800000 + endDate: '2014-01-03T00:00:00-05:00' + endDateMs: 1893474000000 + amount: 9.99 + priceId: 10 + prevPriceId: 11 + plan: + id: 3 + name: Pro Video + desc: Pro Video service and 2 GB disk space + prevPlan: + id: 2 + name: Free Video + desc: Free Video service - delete: - summary: Cancel Call Center Test - operationId: Cancel Call Center Test - description: Cancel a specific test or all active tests. + + /cloud/json/receipt/apple: + post: + summary: Apple Purchase + operationId: Apple Purchase + description: |- + The Care Daily AI Platform supports Apple's Auto-renewable subscriptions + as well as Non-Renewing subscriptions with custom limits on durations. + Please see https://developer.apple.com/in-app-purchase/ for more details. + + When making a purchase through the Apple App Store, the app will hand over control to Apple to handle the transaction. + When the transaction is complete, it is the app's responsibility to capture the authenticated receipt from Apple and reliably pass the receipt to the Care Daily AI Platform. + The Care Daily AI Platform will validate the receipt by calling the payment provider's server, and then securely apply the purchase to the user's account. + + This API will return a result code: + * *0 = Success* + * *6 = Object Not Found*, the receipt is not found on the Apple Store + * *7 = Access Denied*, the receipt is already submitted by a different user + * *8 = Wrong Parameter Value*, The receipt is invalid or expired + * *26 = Duplicate Entry*, The receipt is already submitted by the same user tags: - - Professional Monitoring + - Subscriptions security: - userApiKey: [] parameters: @@ -16143,11 +15991,11 @@ paths: required: true schema: type: integer - - name: testId + - name: appName in: query - description: Test ID + description: Unique app name that is making the purchase schema: - type: integer + type: string responses: '200': description: OK @@ -16161,20 +16009,51 @@ paths: example: resultCode: 0 - /cloud/json/callCenterAlerts: + + /cloud/json/callCenter: get: - summary: Get Call Center Alerts - operationId: Get Call Center Alerts + summary: Get Call Center + operationId: Get Call Center description: |- - Retrieve history of call center alerts. + Retrieve call center service statuses, + if the service is available and if the registration in the third party application has been completed. - The alert source type can have the following values: - | Value | Description | - | :---: | ----------- | - | 0 | Unknown | - | 1 | Raised by a rule | - | 2 | Raised by a composer app | - | 3 | Raised by an app API | + If the service is available, but the registration has not been completed yet, + then the Care Daily AI Platform does not have enough information to do it. + + Call center registration can have following statuses: + + | Value | Status | Description | + | :---: | ------ | ----------- | + | 0 | Unavailable | The service never purchased | + | 1 | Available | The service purchased, but the user does not have enough information for registration | + | 2 | Registration pending | The registration process has not been completed yet | + | 3 | Registered | Registration completed | + | 4 | Cancellation pending | The cancellation has not been completed yet | + | 5 | Canceled | Cancellation completed | + + To complete the call center registration the user has to submit + own name, phone number and address using the update user info API and a list of emergency contacts. + The complete list of missing fields is returned. + + Also, this API returns an array of emergency contacts including the first and the last name, the phone number of the person in the order, how they have to be contacted. + + The alert status with the alert date is returned in a case of an emergency situation. It can have following values: + + | Value | Status | Description | + | :---: | ------ | ----------- | + | 0 | | An alert never raised | + | 1 | Raised | An alert raised, but the call center not contacted yet | + | 3 | Reported | The alert reported to the call center | + + A call center account can be temporaty set to a test mode or scheduled to be on test in the future. + + | Test Status | Description | + | :---------: | ----------- | + | 1 | Test pending | + | 2 | Active now or scheduled | + | 3 | Cancel test pending | + | 4 | Off | Third-party OAuth client supported. tags: @@ -16190,7 +16069,7 @@ paths: type: integer responses: '200': - description: Alerts history + description: Call Center Service content: application/json: schema: @@ -16198,255 +16077,204 @@ paths: properties: resultCode: type: integer - callCenterAlerts: - type: array - items: - type: object - properties: - alertDate: - type: string - alertDateMs: - type: integer - alertStatus: - type: integer - signalType: - type: string - signalMessage: + callCenter: + type: object + properties: + status: + type: integer + description: Service status + code: + type: string + description: External account code + userId: + type: integer + description: Service user's ID + missingFields: + type: array + description: Data fields required for account registration + items: type: string - alertSourceType: - type: integer - device: + contacts: + type: array + description: User contacts to call in case of emergency + items: type: object properties: - id: + userId: + type: integer + description: Existing user's ID, if provided all details will be selected from the user's account + firstName: + type: string + description: First name of a contact not registered in the system + lastName: + type: string + description: Last name of a contact not registered in the system + phone: + type: string + description: Phone number of a contact not registered in the system + phoneType: + type: integer + description: Phone type of a contact not registered in the system + ecv: + type: boolean + description: |- + Contact before bispatch, a value indicating whether the contact will be contacted before attempting to contact dispatch. Enhanced Call Verification. + True by default. + codeword: + type: string + description: Codewords + notDispatch: + type: boolean + description: Set the account dispatch type to "do not dispatch" + permit: + type: string + description: Permit number + alertStatus: + type: integer + description: Alert status + alertDate: + type: string + description: The last alert date + alertDateMs: + type: integer + alertStatusDate: + type: string + alertStatusDateMs: + type: integer + tests: + type: array + description: Test periods + items: + type: object + properties: + testId: + type: integer + status: + type: integer + startDate: + type: string + startDateMs: + type: integer + endDate: type: string - type: + endDateMs: type: integer - goalId: + comment: + type: string + userId: type: integer - typeCategory: + externalTestId: type: integer - desc: - type: string - example: - resultCode: 0 - callCenterAlerts: - - alertDate: '2015-09-01T18:00:00Z' - alertDateMs: 1441130400000 - alertStatus: 3 - signalType: E130 - signalMessage: Motion detected - alertSourceType: 1 - device: - id: 021DE57B-55F0-4FC0-B0AC-9FCB9AF8A001::71 - type: 24 - goalId: 123 - typeCategory: 6 - desc: My camera - - /cloud/json/locations/{locationId}/energyUsage/{aggregation}/{startDate}: - get: - summary: Get Energy Usage for a Location - operationId: Get Energy Usage - tags: - - Energy Management - security: - - userApiKey: [] - parameters: - - name: locationId - in: path - description: Location ID for which to obtain energy measurements - required: true - schema: - type: integer - - name: aggregation - in: path - description: |- - How to aggregate / split the energy data
- 0 - Don't split the data
- 1 - Split by Hour
- 2 - Split by Day
- 3 - Split by Month
- 4 - Split on a 7-day week from Sunday to Saturday
- 5 - Split on a 5-day week from Monday to Friday, and then a 2-day weekend - required: true - schema: - type: integer - enum: [0,1,2,3,4,5] - - name: startDate - in: path - description: Start date to begin receiving measurements - required: true - schema: - type: string - - name: endDate - in: query - description: End date to stop receiving measurements. Default is the current date. - schema: - type: string - responses: - '200': - description: Energy Usage history - content: - application/json: - schema: - type: object - properties: - resultCode: - type: integer - usages: - type: array - items: - type: object - properties: - startDate: - type: string - startDateMs: - type: integer - endDate: - type: string - endDateMs: - type: integer - energy: - type: string - cost: - type: string - external: - type: boolean - required: - - startDate - - startDateMs - - endDate - - endDateMs - - energy - - cost - - external example: resultCode: 0 - usages: - - startDate: '2015-01-01T00:00:00-07:00' - startDateMs: 1420095600000 - endDate: '2015-01-02T00:00:00-07:00' - endDateMs: 1420182000000 - energy: '143.905' - cost: '4.4712' - external: false - - startDate: '2015-01-02T00:00:00-07:00' - startDateMs: 1420182000000 - endDate: '2015-01-03T00:00:00-07:00' - endDateMs: 1420268400000 - energy: '112.361' - cost: '134.8332' - external: false - - startDate: '2015-01-03T00:00:00-07:00' - startDateMs: 1420268400000 - endDate: '2015-01-04T00:00:00-07:00' - endDateMs: 1420354800000 - energy: '116.712' - cost: '48.3527' - external: false - - startDate: '2015-01-04T00:00:00-07:00' - startDateMs: 1420354800000 - endDate: '2015-01-05T00:00:00-07:00' - endDateMs: 1420441200000 - energy: '86.345' - cost: '9.6033' - external: false - - startDate: '2015-01-05T00:00:00-07:00' - startDateMs: 1420441200000 - endDate: '2015-01-06T00:00:00-07:00' - endDateMs: 1420527600000 - energy: '45.984' - cost: '5.0584' - external: false - - startDate: '2015-01-06T00:00:00-07:00' - startDateMs: 1420527600000 - endDate: '2015-01-07T00:00:00-07:00' - endDateMs: 1420614000000 - energy: '36.062' - cost: '3.9670' - external: false - - startDate: '2015-01-07T00:00:00-07:00' - startDateMs: 1420614000000 - endDate: '2015-01-08T00:00:00-07:00' - endDateMs: 1420700400000 - energy: '12.075' - cost: '1.3284' - external: false - - startDate: '2015-01-08T00:00:00-07:00' - startDateMs: 1420700400000 - endDate: '2015-01-09T00:00:00-07:00' - endDateMs: 1420786800000 - energy: '11.961' - cost: '1.3156' - external: false - - startDate: '2015-01-09T00:00:00-07:00' - startDateMs: 1420786800000 - endDate: '2015-01-10T00:00:00-07:00' - endDateMs: 1420873200000 - energy: '118.652' - cost: '13.0520' - external: false - - startDate: '2015-01-10T00:00:00-07:00' - startDateMs: 1420873200000 - endDate: '2015-01-11T00:00:00-07:00' - endDateMs: 1420959600000 - energy: '98.043' - cost: '10.7848' - external: false - - startDate: '2015-01-11T00:00:00-07:00' - startDateMs: 1420959600000 - endDate: '2015-01-12T00:00:00-07:00' - endDateMs: 1421046000000 - energy: '135.291' - cost: '14.8821' - external: false - - startDate: '2015-01-12T00:00:00-07:00' - startDateMs: 1421046000000 - endDate: '2015-01-13T00:00:00-07:00' - endDateMs: 1421132400000 - energy: '10.603' - cost: '1.1663' - external: false - + callCenter: + status: 1 + code: A12345 + userId: 123 + missingFields: + - user.firstName + - user.phone + - location.addrStreet1 + contacts: + - userId: 123 + firstName: Laura + lastName: Secord + phone: '1232686353' + phoneType: 1 + ecv: true + codeword: pass phrase + notDispatch: false + permit: '1234567890' + alertStatus: 3 + alertDate: '2015-09-01T18:00:00Z' + alertDateMs: 1441130400000 + alertStatusDate: '2015-09-01T18:00:30Z' + alertStatusDateMs: 1441130430000 + tests: + - testId: 123 + status: 2 + startDate: '2015-09-01T18:00:30Z' + startDateMs: 1441130430000 + endDate: '2015-09-01T19:00:30Z' + endDateMs: 1441134400000 + comment: One hour test + userId: 456 + externalTestId: 789 - /cloud/json/devices/{deviceId}/currentEnergyUsage: - get: - summary: Get Device Energy Usage - operationId: Get Device Energy Usage + put: + summary: Update Call Center + operationId: Update Call Center description: |- - Return a device's values of power, billing rate, its associated cost, total energy usage, and its cost for the current day, month and year. - - By default, this API returns total device values. - To get the values for the specific part of a device, use an index number (assuming the device supports parameters with index numbers). + Update user's call center record. + The API can raise an alert by setting the alert status. - This method uses the time zone ID from the device location to calculate values. - If the time zone is not set, it uses the default server time zone. + If the new alert status is not provided, the API overwrites the call center contacts information, codeword, permit or location owner user ID. + Submitting null or an empty contacts array will not affect existing contacts data. tags: - - Energy Management + - Professional Monitoring security: - userApiKey: [] parameters: - - name: deviceId - in: path - description: Device ID for which to obtain energy-related data - required: true - schema: - type: string - name: locationId in: query - description: Request information on a specific location + description: Location ID required: true schema: type: integer - - name: index - in: query - description: Optional index number to obtain energy-related data from a part of a device (assuming the device supports index numbers) - schema: - type: string + requestBody: + content: + application/json: + example: + callCenter: + alertStatus: 1 + userId: 123 + contacts: + - userId: 123 + firstName: Laura + lastName: Secord + phone: '1232686353' + phoneType: 1 + ecv: true + codeword: secret + notDispatch: true + permit: '1234567890' + schema: + type: object + properties: + callCenter: + type: object + properties: + alertStatus: + type: integer + description: To raise an alert set it to 1 (raised) + userId: + type: integer + contacts: + type: array + items: + type: object + properties: + userId: + type: integer + firstName: + type: string + lastName: + type: string + phone: + type: string + phoneType: + type: integer + ecv: + type: boolean + codeword: + type: string + notDispatch: + type: boolean + permit: + type: string responses: '200': - description: Current Device Energy Usage + description: OK content: application/json: schema: @@ -16454,110 +16282,42 @@ paths: properties: resultCode: type: integer - power: + callCenter: type: object properties: - amountPerHour: - type: string - watts: - type: string - currentRate: - type: string - lastUpdateDate: - type: string - lastUpdateDateMs: + status: type: integer - energy: - type: object - properties: - amount: - type: string - kwh: - type: string - amountYTD: - type: string - kwhYTD: - type: string - amountDTD: - type: string - kwhDTD: - type: string + missingFields: + type: array + items: + type: string example: resultCode: 0 - power: - amountPerHour: '0.8260' - watts: '8260' - currentRate: '0.1000' - lastUpdateDate: '2014-06-21T22:48:35-07:00' - lastUpdateDateMs: 1403416115000 - energy: - amount: '211.60' - kwh: '2116.000' - amountYTD: '1643.20' - kwhYTD: '16644.000' - amountDTD: '0.00' - kwhDTD: '0.000' - - - /cloud/json/devices/{deviceId}/energyUsage/{aggregation}/{startDate}: - get: - summary: Get Aggregated Energy Usage for a Device - operationId: Get Aggregated Energy Usage for a Device - description: |- - Return energy usage at a device level for a specified period of time, and aggregated by different periods. + callCenter: + status: 1 + missingFields: + - user.firstName + - user.phone + - location.addrStreet1 - This method uses the time zone ID from the device location to calculate values. - If the time zone is not set, it uses the default server time zone. + delete: + summary: Cancel Call Center Account + operationId: Cancel Call Center + description: Update user's call center record status to available and delete contacts. tags: - - Energy Management + - Professional Monitoring security: - userApiKey: [] parameters: - - name: deviceId - in: path - description: Device ID for which to obtain aggregated energy usage - required: true - schema: - type: string - - name: aggregation - in: path - description: |- - How to aggregate / split the energy data
- 0 - Don't split the data
- 1 - Split by Hour
- 2 - Split by Day
- 3 - Split by Month
- 4 - Split on a 7-day week from Sunday to Saturday
- 5 - Split on a 5-day week from Monday to Friday, and then a 2-day weekend - required: true - schema: - type: integer - enum: [0,1,2,3,4,5] - - name: startDate - in: path - description: Start date to begin aggregating energy measurements - required: true - schema: - type: string - - name: endDate - in: query - description: End date to stop aggregating energy measurements. Default is the current date. - schema: - type: string - - name: reduceNoise - in: query - description: Return tiny energy values less than defined threshold as zero - schema: - type: boolean - name: locationId in: query - description: Request information on a specific location + description: Location ID required: true schema: type: integer responses: '200': - description: Aggregated Energy Usage + description: OK content: application/json: schema: @@ -16565,133 +16325,77 @@ paths: properties: resultCode: type: integer - usages: - type: array - items: - type: object - properties: - startDate: - type: string - startDateMs: - type: integer - endDate: - type: string - endDateMs: - type: integer - energy: - type: array - items: - type: object - properties: - index: - type: string - value: - type: string - required: - - index - - value - cost: - type: array - items: - type: object - properties: - index: - type: string - value: - type: string - required: - - index - - value - required: - - startDate - - startDateMs - - endDate - - endDateMs - - energy - - cost example: resultCode: 0 - usages: - - startDate: '2014-10-20T10:00:00-07:00' - startDateMs: 1413824400000 - endDate: '2014-10-20T11:00:00-07:00' - endDateMs: 1413828000000 - energy: - - index: A - value: '0.300' - - index: B - value: '0.500' - cost: - - index: A - value: '0.4000' - - index: B - value: '0.6000' - - startDate: '2014-10-20T14:00:00-07:00' - startDateMs: 1413838800000 - endDate: '2014-10-20T15:00:00-07:00' - endDateMs: 1413842400000 - energy: - - index: B - value: '0.063' - - index: A - value: '0.037' - cost: - - index: B - value: '0.0750' - - index: A - value: '0.0500' + /cloud/json/callCenterTest: + post: + summary: Create Call Center Test + operationId: Create Call Center Test + description: Create a test period for a call center account from optional `startDate` to `endDate`. + tags: + - Professional Monitoring + security: + - userApiKey: [] + parameters: + - name: locationId + in: query + description: Location ID + required: true + schema: + type: integer + requestBody: + content: + application/json: + example: + startDate: '2024-10-18T12:00:00Z' + endDate: '2024-10-18T13:00:00Z' + comment: One hour test comment + schema: + type: object + properties: + startDate: + type: string + endDate: + type: string + comment: + type: string + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + example: + resultCode: 0 - /cloud/json/weather/forecast/geocode/{latitude}/{longitude}: - get: - summary: Get Forecast by Geocode - operationId: Get Forecast by Geocode - description: Retrieve weather forecust at certain point by latitude and longitude. + delete: + summary: Cancel Call Center Test + operationId: Cancel Call Center Test + description: Cancel a specific test or all active tests. tags: - - Weather + - Professional Monitoring security: - userApiKey: [] - - botApiKey: [] parameters: - - name: latitude - in: path - description: Latitude - required: true - schema: - type: string - - name: longitude - in: path - description: Longitude - required: true - schema: - type: string - - name: units - in: query - description: |- - Units for measurements, default value is "Metric". -
Available values are: -
e = English units, -
m = Metric units, -
h = Hybrid units (UK), -
s = Metric SI units (not available for all APIs) - schema: - type: string - - name: hours + - name: locationId in: query - description: |- - Forecast depth in hours. -
Available values are: 6, 12, 24,48. -
Default value is 24. + description: Location ID + required: true schema: type: integer - - name: organizationId + - name: testId in: query - description: For specific organization. Used by administrator only. + description: Test ID schema: type: integer responses: '200': - description: Forecast + description: OK content: application/json: schema: @@ -16699,288 +16403,39 @@ paths: properties: resultCode: type: integer - weather: - type: object - properties: - metadata: - type: object - properties: - language: - type: string - transaction_id: - type: string - version: - type: string - latitude: - type: integer - longitude: - type: integer - units: - type: string - expire_time_gmt: - type: integer - status_code: - type: integer - forecasts: - type: array - items: - type: object - properties: - class: - type: string - expire_time_gmt: - type: integer - fcst_valid: - type: integer - fcst_valid_local: - type: string - num: - type: integer - day_ind: - type: string - temp: - type: integer - dewpt: - type: integer - hi: - type: integer - wc: - type: integer - feels_like: - type: integer - icon_extd: - type: integer - wxman: - type: string - icon_code: - type: integer - dow: - type: string - phrase_12char: - type: string - phrase_22char: - type: string - phrase_32char: - type: string - subphrase_pt1: - type: string - subphrase_pt2: - type: string - subphrase_pt3: - type: string - pop: - type: integer - precip_type: - type: string - qpf: - type: integer - snow_qpf: - type: integer - rh: - type: integer - wspd: - type: integer - wdir: - type: integer - wdir_cardinal: - type: string - gust: - type: integer - clds: - type: integer - vis: - type: integer - mslp: - type: integer - uv_index_raw: - type: integer - uv_index: - type: integer - uv_warning: - type: integer - uv_desc: - type: string - golf_index: - type: integer - golf_category: - type: string - severity: - type: integer - required: - - class - - expire_time_gmt - - fcst_valid - - fcst_valid_local - - num - - day_ind - - temp - - dewpt - - hi - - wc - - feels_like - - icon_extd - - wxman - - icon_code - - dow - - phrase_12char - - phrase_22char - - phrase_32char - - subphrase_pt1 - - subphrase_pt2 - - subphrase_pt3 - - pop - - precip_type - - qpf - - snow_qpf - - rh - - wspd - - wdir - - wdir_cardinal - - gust - - clds - - vis - - mslp - - uv_index_raw - - uv_index - - uv_warning - - uv_desc - - golf_index - - golf_category - - severity example: resultCode: 0 - weather: - metadata: - language: en-US - transaction_id: 1493118110823:-2023430256 - version: '1' - latitude: 30 - longitude: 40 - units: m - expire_time_gmt: 1493118710 - status_code: 200 - forecasts: - - class: fod_short_range_hourly - expire_time_gmt: 1493118710 - fcst_valid: 1493121600 - fcst_valid_local: 2017-04-25T15:00:00+0300 - num: 1 - day_ind: D - temp: 28 - dewpt: 1 - hi: 28 - wc: 28 - feels_like: 28 - icon_extd: 3200 - wxman: wx1000 - icon_code: 32 - dow: Tuesday - phrase_12char: Sunny - phrase_22char: Sunny - phrase_32char: Sunny - subphrase_pt1: Sunny - subphrase_pt2: '' - subphrase_pt3: '' - pop: 0 - precip_type: rain - qpf: 0 - snow_qpf: 0 - rh: 17 - wspd: 19 - wdir: 67 - wdir_cardinal: ENE - gust: null - clds: 0 - vis: 16 - mslp: 1013.2 - uv_index_raw: 5.47 - uv_index: 5 - uv_warning: 0 - uv_desc: Moderate - golf_index: 9 - golf_category: Very Good - severity: 1 - - class: fod_long_range_hourly - expire_time_gmt: 1493119910 - fcst_valid: 1493204400 - fcst_valid_local: 2017-04-26T14:00:00+0300 - num: 24 - day_ind: D - temp: 29 - dewpt: -1 - hi: 29 - wc: 29 - feels_like: 29 - icon_extd: 3200 - wxman: wx1000 - icon_code: 32 - dow: Wednesday - phrase_12char: Sunny - phrase_22char: Sunny - phrase_32char: Sunny - subphrase_pt1: Sunny - subphrase_pt2: '' - subphrase_pt3: '' - pop: 0 - precip_type: rain - qpf: 0 - snow_qpf: 0 - rh: 13 - wspd: 28 - wdir: 86 - wdir_cardinal: E - gust: null - clds: 9 - vis: 16 - mslp: 1013.8 - uv_index_raw: 8.04 - uv_index: 8 - uv_warning: 0 - uv_desc: Very High - golf_index: 9 - golf_category: Very Good - severity: 1 - - - /cloud/json/weather/forecast/location/{locationId}: + + /cloud/json/callCenterAlerts: get: - summary: Get Forecast by Location - operationId: Get Forecast by Location - description: Retrieve weather forecast by the location address. + summary: Get Call Center Alerts + operationId: Get Call Center Alerts + description: |- + Retrieve history of call center alerts. + + The alert source type can have the following values: + | Value | Description | + | :---: | ----------- | + | 0 | Unknown | + | 1 | Raised by a rule | + | 2 | Raised by a composer app | + | 3 | Raised by an app API | + + Third-party OAuth client supported. tags: - - Weather + - Professional Monitoring security: - userApiKey: [] - - botApiKey: [] parameters: - name: locationId - in: path - description: ID of location - required: true - schema: - type: integer - - name: units - in: query - description: |- - Units for measurements, default value is "Metric". -
Available values are: -
e = English units, -
m = Metric units, -
h = Hybrid units (UK), -
s = Metric SI units (not available for all APIs) - schema: - type: string - - name: hours in: query - description: |- - Forecast depth in hours. -
Available values are: 6, 12, 24,48. -
Default value is 24. + description: Location ID + required: true schema: type: integer responses: '200': - description: Forecast + description: Alerts history content: application/json: schema: @@ -16988,291 +16443,255 @@ paths: properties: resultCode: type: integer - weather: - type: object - properties: - metadata: - type: object - properties: - language: - type: string - transaction_id: - type: string - version: - type: string - latitude: - type: integer - longitude: - type: integer - units: - type: string - expire_time_gmt: - type: integer - status_code: - type: integer - forecasts: - type: array - items: + callCenterAlerts: + type: array + items: + type: object + properties: + alertDate: + type: string + alertDateMs: + type: integer + alertStatus: + type: integer + signalType: + type: string + signalMessage: + type: string + alertSourceType: + type: integer + device: type: object properties: - class: - type: string - expire_time_gmt: - type: integer - fcst_valid: - type: integer - fcst_valid_local: - type: string - num: - type: integer - day_ind: - type: string - temp: - type: integer - dewpt: - type: integer - hi: - type: integer - wc: - type: integer - feels_like: - type: integer - icon_extd: - type: integer - wxman: - type: string - icon_code: - type: integer - dow: - type: string - phrase_12char: - type: string - phrase_22char: - type: string - phrase_32char: - type: string - subphrase_pt1: - type: string - subphrase_pt2: - type: string - subphrase_pt3: - type: string - pop: - type: integer - precip_type: - type: string - qpf: - type: integer - snow_qpf: - type: integer - rh: - type: integer - wspd: - type: integer - wdir: - type: integer - wdir_cardinal: + id: type: string - gust: - type: integer - clds: - type: integer - vis: - type: integer - mslp: - type: integer - uv_index_raw: - type: integer - uv_index: + type: type: integer - uv_warning: + goalId: type: integer - uv_desc: - type: string - golf_index: + typeCategory: type: integer - golf_category: + desc: type: string - severity: - type: integer - required: - - class - - expire_time_gmt - - fcst_valid - - fcst_valid_local - - num - - day_ind - - temp - - dewpt - - hi - - wc - - feels_like - - icon_extd - - wxman - - icon_code - - dow - - phrase_12char - - phrase_22char - - phrase_32char - - subphrase_pt1 - - subphrase_pt2 - - subphrase_pt3 - - pop - - precip_type - - qpf - - snow_qpf - - rh - - wspd - - wdir - - wdir_cardinal - - gust - - clds - - vis - - mslp - - uv_index_raw - - uv_index - - uv_warning - - uv_desc - - golf_index - - golf_category - - severity example: resultCode: 0 - weather: - metadata: - language: en-US - transaction_id: 1493118110823:-2023430256 - version: '1' - latitude: 30 - longitude: 40 - units: m - expire_time_gmt: 1493118710 - status_code: 200 - forecasts: - - class: fod_short_range_hourly - expire_time_gmt: 1493118710 - fcst_valid: 1493121600 - fcst_valid_local: 2017-04-25T15:00:00+0300 - num: 1 - day_ind: D - temp: 28 - dewpt: 1 - hi: 28 - wc: 28 - feels_like: 28 - icon_extd: 3200 - wxman: wx1000 - icon_code: 32 - dow: Tuesday - phrase_12char: Sunny - phrase_22char: Sunny - phrase_32char: Sunny - subphrase_pt1: Sunny - subphrase_pt2: '' - subphrase_pt3: '' - pop: 0 - precip_type: rain - qpf: 0 - snow_qpf: 0 - rh: 17 - wspd: 19 - wdir: 67 - wdir_cardinal: ENE - gust: null - clds: 0 - vis: 16 - mslp: 1013.2 - uv_index_raw: 5.47 - uv_index: 5 - uv_warning: 0 - uv_desc: Moderate - golf_index: 9 - golf_category: Very Good - severity: 1 - - class: fod_long_range_hourly - expire_time_gmt: 1493119910 - fcst_valid: 1493204400 - fcst_valid_local: 2017-04-26T14:00:00+0300 - num: 24 - day_ind: D - temp: 29 - dewpt: -1 - hi: 29 - wc: 29 - feels_like: 29 - icon_extd: 3200 - wxman: wx1000 - icon_code: 32 - dow: Wednesday - phrase_12char: Sunny - phrase_22char: Sunny - phrase_32char: Sunny - subphrase_pt1: Sunny - subphrase_pt2: '' - subphrase_pt3: '' - pop: 0 - precip_type: rain - qpf: 0 - snow_qpf: 0 - rh: 13 - wspd: 28 - wdir: 86 - wdir_cardinal: E - gust: null - clds: 9 - vis: 16 - mslp: 1013.8 - uv_index_raw: 8.04 - uv_index: 8 - uv_warning: 0 - uv_desc: Very High - golf_index: 9 - golf_category: Very Good - severity: 1 - - - /cloud/json/weather/current/geocode/{latitude}/{longitude}: + callCenterAlerts: + - alertDate: '2015-09-01T18:00:00Z' + alertDateMs: 1441130400000 + alertStatus: 3 + signalType: E130 + signalMessage: Motion detected + alertSourceType: 1 + device: + id: 021DE57B-55F0-4FC0-B0AC-9FCB9AF8A001::71 + type: 24 + goalId: 123 + typeCategory: 6 + desc: My camera + + /cloud/json/locations/{locationId}/energyUsage/{aggregation}/{startDate}: + get: + summary: Get Energy Usage for a Location + operationId: Get Energy Usage + tags: + - Energy Management + security: + - userApiKey: [] + parameters: + - name: locationId + in: path + description: Location ID for which to obtain energy measurements + required: true + schema: + type: integer + - name: aggregation + in: path + description: |- + How to aggregate / split the energy data
+ 0 - Don't split the data
+ 1 - Split by Hour
+ 2 - Split by Day
+ 3 - Split by Month
+ 4 - Split on a 7-day week from Sunday to Saturday
+ 5 - Split on a 5-day week from Monday to Friday, and then a 2-day weekend + required: true + schema: + type: integer + enum: [0,1,2,3,4,5] + - name: startDate + in: path + description: Start date to begin receiving measurements + required: true + schema: + type: string + - name: endDate + in: query + description: End date to stop receiving measurements. Default is the current date. + schema: + type: string + responses: + '200': + description: Energy Usage history + content: + application/json: + schema: + type: object + properties: + resultCode: + type: integer + usages: + type: array + items: + type: object + properties: + startDate: + type: string + startDateMs: + type: integer + endDate: + type: string + endDateMs: + type: integer + energy: + type: string + cost: + type: string + external: + type: boolean + required: + - startDate + - startDateMs + - endDate + - endDateMs + - energy + - cost + - external + example: + resultCode: 0 + usages: + - startDate: '2015-01-01T00:00:00-07:00' + startDateMs: 1420095600000 + endDate: '2015-01-02T00:00:00-07:00' + endDateMs: 1420182000000 + energy: '143.905' + cost: '4.4712' + external: false + - startDate: '2015-01-02T00:00:00-07:00' + startDateMs: 1420182000000 + endDate: '2015-01-03T00:00:00-07:00' + endDateMs: 1420268400000 + energy: '112.361' + cost: '134.8332' + external: false + - startDate: '2015-01-03T00:00:00-07:00' + startDateMs: 1420268400000 + endDate: '2015-01-04T00:00:00-07:00' + endDateMs: 1420354800000 + energy: '116.712' + cost: '48.3527' + external: false + - startDate: '2015-01-04T00:00:00-07:00' + startDateMs: 1420354800000 + endDate: '2015-01-05T00:00:00-07:00' + endDateMs: 1420441200000 + energy: '86.345' + cost: '9.6033' + external: false + - startDate: '2015-01-05T00:00:00-07:00' + startDateMs: 1420441200000 + endDate: '2015-01-06T00:00:00-07:00' + endDateMs: 1420527600000 + energy: '45.984' + cost: '5.0584' + external: false + - startDate: '2015-01-06T00:00:00-07:00' + startDateMs: 1420527600000 + endDate: '2015-01-07T00:00:00-07:00' + endDateMs: 1420614000000 + energy: '36.062' + cost: '3.9670' + external: false + - startDate: '2015-01-07T00:00:00-07:00' + startDateMs: 1420614000000 + endDate: '2015-01-08T00:00:00-07:00' + endDateMs: 1420700400000 + energy: '12.075' + cost: '1.3284' + external: false + - startDate: '2015-01-08T00:00:00-07:00' + startDateMs: 1420700400000 + endDate: '2015-01-09T00:00:00-07:00' + endDateMs: 1420786800000 + energy: '11.961' + cost: '1.3156' + external: false + - startDate: '2015-01-09T00:00:00-07:00' + startDateMs: 1420786800000 + endDate: '2015-01-10T00:00:00-07:00' + endDateMs: 1420873200000 + energy: '118.652' + cost: '13.0520' + external: false + - startDate: '2015-01-10T00:00:00-07:00' + startDateMs: 1420873200000 + endDate: '2015-01-11T00:00:00-07:00' + endDateMs: 1420959600000 + energy: '98.043' + cost: '10.7848' + external: false + - startDate: '2015-01-11T00:00:00-07:00' + startDateMs: 1420959600000 + endDate: '2015-01-12T00:00:00-07:00' + endDateMs: 1421046000000 + energy: '135.291' + cost: '14.8821' + external: false + - startDate: '2015-01-12T00:00:00-07:00' + startDateMs: 1421046000000 + endDate: '2015-01-13T00:00:00-07:00' + endDateMs: 1421132400000 + energy: '10.603' + cost: '1.1663' + external: false + + + /cloud/json/devices/{deviceId}/currentEnergyUsage: get: - summary: Get Current Weather by Geocode - operationId: Get Current Weather by Geocode - description: Retrieve current weather at certain point by latitude and longitude. + summary: Get Device Energy Usage + operationId: Get Device Energy Usage + description: |- + Return a device's values of power, billing rate, its associated cost, total energy usage, and its cost for the current day, month and year. + + By default, this API returns total device values. + To get the values for the specific part of a device, use an index number (assuming the device supports parameters with index numbers). + + This method uses the time zone ID from the device location to calculate values. + If the time zone is not set, it uses the default server time zone. tags: - - Weather + - Energy Management security: - userApiKey: [] - - botApiKey: [] parameters: - - name: latitude + - name: deviceId in: path - description: Latitude + description: Device ID for which to obtain energy-related data required: true schema: type: string - - name: longitude - in: path - description: Longitude + - name: locationId + in: query + description: Request information on a specific location required: true schema: - type: string - - name: units + type: integer + - name: index in: query - description: |- - Units for measurements, default value is "Metric". -
Available values are: -
e = English units, -
m = Metric units, -
h = Hybrid units (UK), -
s = Metric SI units (not available for all APIs) + description: Optional index number to obtain energy-related data from a part of a device (assuming the device supports index numbers) schema: type: string - - name: organizationId - in: query - description: For specific organization. Used by administrator only. - schema: - type: integer responses: '200': - description: Current Weather + description: Current Device Energy Usage content: application/json: schema: @@ -17280,267 +16699,110 @@ paths: properties: resultCode: type: integer - weather: + power: type: object properties: - metadata: - type: object - properties: - language: - type: string - transaction_id: - type: string - version: - type: string - latitude: - type: integer - longitude: - type: integer - units: - type: string - expire_time_gmt: - type: integer - status_code: - type: integer - observation: - type: object - properties: - class: - type: string - expire_time_gmt: - type: integer - obs_time: - type: integer - obs_time_local: - type: string - wdir: - type: integer - icon_code: - type: integer - icon_extd: - type: integer - sunrise: - type: string - sunset: - type: string - day_ind: - type: string - uv_index: - type: integer - uv_warning: - type: integer - wxman: - type: string - obs_qualifier_code: - type: integer - ptend_code: - type: integer - dow: - type: string - wdir_cardinal: - type: string - uv_desc: - type: string - phrase_12char: - type: string - phrase_22char: - type: string - phrase_32char: - type: string - ptend_desc: - type: string - sky_cover: - type: string - clds: - type: string - obs_qualifier_severity: - type: integer - vocal_key: - type: string - metric: - type: object - properties: - wspd: - type: integer - gust: - type: integer - vis: - type: integer - mslp: - type: integer - altimeter: - type: integer - temp: - type: integer - dewpt: - type: integer - rh: - type: integer - wc: - type: integer - hi: - type: integer - temp_change_24hour: - type: integer - temp_max_24hour: - type: integer - temp_min_24hour: - type: integer - pchange: - type: integer - feels_like: - type: integer - snow_1hour: - type: integer - snow_6hour: - type: integer - snow_24hour: - type: integer - snow_mtd: - type: integer - snow_season: - type: integer - snow_ytd: - type: integer - snow_2day: - type: integer - snow_3day: - type: integer - snow_7day: - type: integer - ceiling: - type: integer - precip_1hour: - type: integer - precip_6hour: - type: integer - precip_24hour: - type: integer - precip_mtd: - type: integer - precip_ytd: - type: integer - precip_2day: - type: integer - precip_3day: - type: integer - precip_7day: - type: integer - obs_qualifier_100char: - type: integer - obs_qualifier_50char: - type: integer - obs_qualifier_32char: - type: integer + amountPerHour: + type: string + watts: + type: string + currentRate: + type: string + lastUpdateDate: + type: string + lastUpdateDateMs: + type: integer + energy: + type: object + properties: + amount: + type: string + kwh: + type: string + amountYTD: + type: string + kwhYTD: + type: string + amountDTD: + type: string + kwhDTD: + type: string example: resultCode: 0 - weather: - metadata: - language: en-US - transaction_id: 1493117273822:-620374915 - version: '1' - latitude: 30 - longitude: 40 - units: m - expire_time_gmt: 1493117873 - status_code: 200 - observation: - class: observation - expire_time_gmt: 1493117873 - obs_time: 1493117273 - obs_time_local: 2017-04-25T13:47:53+0300 - wdir: 60 - icon_code: 32 - icon_extd: 3200 - sunrise: 2017-04-25T05:42:39+0300 - sunset: 2017-04-25T18:53:41+0300 - day_ind: D - uv_index: 8 - uv_warning: 0 - wxman: wx1000 - obs_qualifier_code: null - ptend_code: 2 - dow: Tuesday - wdir_cardinal: ENE - uv_desc: Very High - phrase_12char: Sunny - phrase_22char: Sunny - phrase_32char: Sunny - ptend_desc: Falling - sky_cover: Clear - clds: CLR - obs_qualifier_severity: null - vocal_key: OT81:OX3200 - metric: - wspd: 21 - gust: null - vis: 14.48 - mslp: 1014.6 - altimeter: 1014.22 - temp: 27 - dewpt: 0 - rh: 17 - wc: 27 - hi: 27 - temp_change_24hour: -18 - temp_max_24hour: 29 - temp_min_24hour: 17 - pchange: -2.03 - feels_like: 27 - snow_1hour: 0 - snow_6hour: 0 - snow_24hour: 0 - snow_mtd: null - snow_season: null - snow_ytd: null - snow_2day: null - snow_3day: null - snow_7day: null - ceiling: null - precip_1hour: 0 - precip_6hour: 0 - precip_24hour: 0 - precip_mtd: null - precip_ytd: null - precip_2day: null - precip_3day: null - precip_7day: null - obs_qualifier_100char: null - obs_qualifier_50char: null - obs_qualifier_32char: null - - - /cloud/json/weather/current/location/{locationId}: + power: + amountPerHour: '0.8260' + watts: '8260' + currentRate: '0.1000' + lastUpdateDate: '2014-06-21T22:48:35-07:00' + lastUpdateDateMs: 1403416115000 + energy: + amount: '211.60' + kwh: '2116.000' + amountYTD: '1643.20' + kwhYTD: '16644.000' + amountDTD: '0.00' + kwhDTD: '0.000' + + + /cloud/json/devices/{deviceId}/energyUsage/{aggregation}/{startDate}: get: - summary: Get Current Weather by Location - operationId: Get Current Weather by Location - description: Retrieve current weather at the specific location. + summary: Get Aggregated Energy Usage for a Device + operationId: Get Aggregated Energy Usage for a Device + description: |- + Return energy usage at a device level for a specified period of time, and aggregated by different periods. + + This method uses the time zone ID from the device location to calculate values. + If the time zone is not set, it uses the default server time zone. tags: - - Weather + - Energy Management security: - userApiKey: [] - - botApiKey: [] parameters: - - name: locationId + - name: deviceId + in: path + description: Device ID for which to obtain aggregated energy usage + required: true + schema: + type: string + - name: aggregation in: path - description: ID of location + description: |- + How to aggregate / split the energy data
+ 0 - Don't split the data
+ 1 - Split by Hour
+ 2 - Split by Day
+ 3 - Split by Month
+ 4 - Split on a 7-day week from Sunday to Saturday
+ 5 - Split on a 5-day week from Monday to Friday, and then a 2-day weekend required: true schema: type: integer - - name: units + enum: [0,1,2,3,4,5] + - name: startDate + in: path + description: Start date to begin aggregating energy measurements + required: true + schema: + type: string + - name: endDate in: query - description: |- - Units for measurements, default value is "Metric". -
Available values are: -
e = English units, -
m = Metric units, -
h = Hybrid units (UK), -
s = Metric SI units (not available for all APIs) + description: End date to stop aggregating energy measurements. Default is the current date. schema: type: string + - name: reduceNoise + in: query + description: Return tiny energy values less than defined threshold as zero + schema: + type: boolean + - name: locationId + in: query + description: Request information on a specific location + required: true + schema: + type: integer responses: '200': - description: Current Weather + description: Aggregated Energy Usage content: application/json: schema: @@ -17548,234 +16810,81 @@ paths: properties: resultCode: type: integer - weather: - type: object - properties: - metadata: - type: object - properties: - language: - type: string - transaction_id: - type: string - version: - type: string - latitude: - type: integer - longitude: - type: integer - units: - type: string - expire_time_gmt: - type: integer - status_code: - type: integer - observation: - type: object - properties: - class: - type: string - expire_time_gmt: - type: integer - obs_time: - type: integer - obs_time_local: - type: string - wdir: - type: integer - icon_code: - type: integer - icon_extd: - type: integer - sunrise: - type: string - sunset: - type: string - day_ind: - type: string - uv_index: - type: integer - uv_warning: - type: integer - wxman: - type: string - obs_qualifier_code: - type: integer - ptend_code: - type: integer - dow: - type: string - wdir_cardinal: - type: string - uv_desc: - type: string - phrase_12char: - type: string - phrase_22char: - type: string - phrase_32char: - type: string - ptend_desc: - type: string - sky_cover: - type: string - clds: - type: string - obs_qualifier_severity: - type: integer - vocal_key: - type: string - metric: + usages: + type: array + items: + type: object + properties: + startDate: + type: string + startDateMs: + type: integer + endDate: + type: string + endDateMs: + type: integer + energy: + type: array + items: type: object properties: - wspd: - type: integer - gust: - type: integer - vis: - type: integer - mslp: - type: integer - altimeter: - type: integer - temp: - type: integer - dewpt: - type: integer - rh: - type: integer - wc: - type: integer - hi: - type: integer - temp_change_24hour: - type: integer - temp_max_24hour: - type: integer - temp_min_24hour: - type: integer - pchange: - type: integer - feels_like: - type: integer - snow_1hour: - type: integer - snow_6hour: - type: integer - snow_24hour: - type: integer - snow_mtd: - type: integer - snow_season: - type: integer - snow_ytd: - type: integer - snow_2day: - type: integer - snow_3day: - type: integer - snow_7day: - type: integer - ceiling: - type: integer - precip_1hour: - type: integer - precip_6hour: - type: integer - precip_24hour: - type: integer - precip_mtd: - type: integer - precip_ytd: - type: integer - precip_2day: - type: integer - precip_3day: - type: integer - precip_7day: - type: integer - obs_qualifier_100char: - type: integer - obs_qualifier_50char: - type: integer - obs_qualifier_32char: - type: integer + index: + type: string + value: + type: string + required: + - index + - value + cost: + type: array + items: + type: object + properties: + index: + type: string + value: + type: string + required: + - index + - value + required: + - startDate + - startDateMs + - endDate + - endDateMs + - energy + - cost example: resultCode: 0 - weather: - metadata: - language: en-US - transaction_id: 1493117273822:-620374915 - version: '1' - latitude: 30 - longitude: 40 - units: m - expire_time_gmt: 1493117873 - status_code: 200 - observation: - class: observation - expire_time_gmt: 1493117873 - obs_time: 1493117273 - obs_time_local: 2017-04-25T13:47:53+0300 - wdir: 60 - icon_code: 32 - icon_extd: 3200 - sunrise: 2017-04-25T05:42:39+0300 - sunset: 2017-04-25T18:53:41+0300 - day_ind: D - uv_index: 8 - uv_warning: 0 - wxman: wx1000 - obs_qualifier_code: null - ptend_code: 2 - dow: Tuesday - wdir_cardinal: ENE - uv_desc: Very High - phrase_12char: Sunny - phrase_22char: Sunny - phrase_32char: Sunny - ptend_desc: Falling - sky_cover: Clear - clds: CLR - obs_qualifier_severity: null - vocal_key: OT81:OX3200 - metric: - wspd: 21 - gust: null - vis: 14.48 - mslp: 1014.6 - altimeter: 1014.22 - temp: 27 - dewpt: 0 - rh: 17 - wc: 27 - hi: 27 - temp_change_24hour: -18 - temp_max_24hour: 29 - temp_min_24hour: 17 - pchange: -2.03 - feels_like: 27 - snow_1hour: 0 - snow_6hour: 0 - snow_24hour: 0 - snow_mtd: null - snow_season: null - snow_ytd: null - snow_2day: null - snow_3day: null - snow_7day: null - ceiling: null - precip_1hour: 0 - precip_6hour: 0 - precip_24hour: 0 - precip_mtd: null - precip_ytd: null - precip_2day: null - precip_3day: null - precip_7day: null - obs_qualifier_100char: null - obs_qualifier_50char: null - obs_qualifier_32char: null + usages: + - startDate: '2014-10-20T10:00:00-07:00' + startDateMs: 1413824400000 + endDate: '2014-10-20T11:00:00-07:00' + endDateMs: 1413828000000 + energy: + - index: A + value: '0.300' + - index: B + value: '0.500' + cost: + - index: A + value: '0.4000' + - index: B + value: '0.6000' + - startDate: '2014-10-20T14:00:00-07:00' + startDateMs: 1413838800000 + endDate: '2014-10-20T15:00:00-07:00' + endDateMs: 1413842400000 + energy: + - index: B + value: '0.063' + - index: A + value: '0.037' + cost: + - index: B + value: '0.0750' + - index: A + value: '0.0500' /cloud/json/deviceTypes: @@ -17808,16 +16917,6 @@ paths: description: Return only device types created by this user schema: type: boolean - - name: simple - in: query - description: Return only device type fields without user and attributes information - schema: - type: boolean - - name: organizationId - in: query - description: Return only device types related to the specific organization - schema: - type: integer responses: '200': description: Device Types @@ -17859,16 +16958,13 @@ paths: properties: email: type: string - verified: - type: boolean - status: - type: integer creationDate: type: string creationDateMs: type: integer attributes: type: array + description: Device type attributes items: type: object properties: @@ -17879,6 +16975,25 @@ paths: required: - name - value + deviceParams: + type: array + description: Device type specific parameters + items: + type: object + properties: + name: + type: string + description: Parameter name + getable: + type: boolean + description: Can be retrieved by sending a get command to the device + setable: + type: boolean + description: Can be updated on the device by sending a set command to the device + required: + - name + - getable + - setable required: - id - name @@ -17896,8 +17011,6 @@ paths: lastName: Smith email: email: john@smith.com - verified: true - status: 0 creationDate: '2015-02-27T15:30:21Z' creationDateMs: 1425051021000 attributes: @@ -18819,6 +17932,12 @@ paths: required: true schema: type: integer + - name: locationId + in: query + description: The rule's location ID + required: true + schema: + type: integer - name: hidden in: query description: |- @@ -20895,7 +20014,6 @@ tags: ru - Russian
etc - medicalRecordNumberstringMedical Record Number pronounIdintegerUser's pronoun ID. See the get pronouns API. avatarFileIdintegerAvatar app file ID phonestringPhone number @@ -20942,7 +20060,7 @@ tags: When creating or updating location information in a user's account, all fields are optional: - + - + + -
RequestDescriptionDetails
RequestTypeDescription
namestringName of the location (i.e. "My House" or "Upstairs Bedroom")
typenumeric 10 - Residence
@@ -20975,7 +20093,8 @@ tags: See the Date and Time Formats for more details.
appNamestringApp name used to create this location
languagestringPreferred language for location states and narratives
externalIdstringLocation's ID in partner's cloud
externalIdstringSingle location's ID in partner's cloud
externalLocationsarrayArray of partner identifiers of this location.
locationUserobjectUser properties on the location
fileUploadPolicyinteger 0 - Keep old files
@@ -21001,21 +20120,19 @@ tags:
latitudestringThe latitude in degrees
longitudestringThe longitude in degrees
testbooleanThis is a test location.
codeTypeintegerLocation code type
- name: Locations - - name: Synthetic APIs + - name: Location Events description: |- - Synthetic APIs are provided exclusively by bots which run at the application layer. + Location Events is a a group of APIs related to business logic provided by bots which run at the application layer. - Advantages to Synthetic APIs include: + Advantages to Location Event APIs include: * Faster time-to-market * Rapid development of application capabilities without involving server engineering or QA platform regression testing * End-user facing capabilities can expand and contract based on the availability of subscriptions and bots - Specific Synthetic APIs are documented separately since they are not part of the platform itself. This style of API design is asynchronous or "split-phase", where a Data Stream Message forms the input to the API offered by a bot, and a State variable forms the output. Both data stream messages and state variables have addresses as keys, and arbitrary JSON content as values. @@ -21133,6 +20250,14 @@ tags: We connect with a 5-diamond certified central station in North America. This can be replaced with your own professional monitoring call center to enable international services and professional monitoring. + - name: Clouds Integration + description: |- + OAuth 2.0 allows the Care Daily AI Platform to act as a client to obtain authorizations from third-party clouds and applications to access user data there. + + - name: OAuth Hosting + description: |- + As a host the Care Daily AI Platform can provide data to OAuth 2.0 clients. + - name: Device Files description: |- The Care Daily AI Platform securely manages sensitive binary files associated with a user's account. @@ -21512,14 +20637,6 @@ tags: | M | 1000000 | Mega | | G | 1000000000 | Giga | - - name: Clouds Integration - description: |- - OAuth 2.0 allows the Care Daily AI Platform to act as a client to obtain authorizations from third-party clouds and applications to access user data there. - - - name: OAuth Hosting - description: |- - As a host the Care Daily AI Platform can provide data to OAuth 2.0 clients. - - name: Energy Management description: |- Electricity customers are billed on how much energy their homes, businesses, and appliances consume. @@ -21527,7 +20644,4 @@ tags: The Care Daily AI Platform contains a Utility Rates Database in the backend to map utility names to their current rates and pricing information. This data can help smooth out the deployment of energy-related programs, - and greatly improve the user experience by converting the nebulous units of kilowatt-hours into something more user-friendly, like monetary value. - - - name: Weather - description: These APIs are available for certain organizations only. \ No newline at end of file + and greatly improve the user experience by converting the nebulous units of kilowatt-hours into something more user-friendly, like monetary value. \ No newline at end of file diff --git a/okf/apis/api-surface.md b/okf/apis/api-surface.md index 12fda39..47a68bd 100644 --- a/okf/apis/api-surface.md +++ b/okf/apis/api-surface.md @@ -5,17 +5,17 @@ description: Every API class by subpackage (app / admin / bot), the factory that resource: peoplepower/python-core:src/caredaily/apis tags: [python-core, apis, reference] status: draft -generated: { by: claude_code/claude-fable-5, at: 2026-09-11T00:00:00Z } +generated: { by: claude_code/claude-opus-5-5, at: 2026-10-05T00:00:00Z } stale_after: 2027-03-11T00:00:00Z sources: - id: apis-init resource: peoplepower/python-core:src/caredaily/apis/__init__.py title: apis package exports - last_modified: 2026-07-10T23:03:51-07:00 + last_modified: 2026-10-05T00:00:00-07:00 - id: caredaily resource: peoplepower/python-core:src/caredaily/caredaily.py title: Factory if-chains - last_modified: 2026-07-10T23:03:51-07:00 + last_modified: 2026-10-05T00:00:00-07:00 --- All classes inherit from `API` and are served by the matching @@ -28,7 +28,11 @@ endpoint docs: . `Locations`, `Devices`, `DeviceMeasurements`, `DeviceTypesAndParameters`, `DeviceFiles`, `AppFiles`, `UserCommunication`, `SystemAndUserProperties`, `Rules`, `PaidServices`, `ProfessionalMonitoring`, `EnergyManagement`, -`Weather`, `CloudConnectivity`, `CloudsIntegration`, `RAG`, `AI`, `Websocket`. +`CloudConnectivity`, `CloudsIntegration`, `RAG`, `AI`, `Websocket`. + +`Weather` (app) and `Challenges` (admin) were removed in SDK 1.0.3 when the +server dropped those endpoints in API spec v65. Escalations (spec v65, +`/cloud/json/escalations`) live on `Locations` alongside narratives. App APIs migrated from legacy `/espapi/cloud/json/` to `/cloud/json/` on 2026-07-07 — the espapi route cannot validate EdDSA JWT API keys @@ -42,7 +46,7 @@ adapter: it fetches the websocket URL via REST, then provides an async client # Admin APIs — `cd.admin_api(...)`, `/admin/json/...` `apis/admin/`: `System`, `Organizations`, `Groups`, `Users`, `UserGroups`, -`AdminDevices`, `AdminLocations`, `AdminTags`, `Challenges`, `Narratives`, +`AdminDevices`, `AdminLocations`, `AdminTags`, `Narratives`, `Billing`, `Firmware`, `Reports`. A few admin APIs (narratives, tags, groups) still use legacy diff --git a/okf/log.md b/okf/log.md index a4a7439..0561fa1 100644 --- a/okf/log.md +++ b/okf/log.md @@ -1,5 +1,9 @@ # Log +## 2026-10-05 + +* **Update**: Server API spec v63 → v65. Removed the `Weather` (app) and `Challenges` (admin) API classes and their factory entries, user codes methods on `UserAccounts`, and bot `Analytic.get_challenge_participants`; added escalations (`get/create/update_escalation`) on `Locations`. Updated the api-surface concept. + ## 2026-09-11 * **Update**: Recorded the new Claude Code project skill `.claude/skills/caredaily/SKILL.md` (SDK/CLI usage guide: factories, auth flows including TOTP/RSA signature, gotchas) in the repo-layout concept, along with the `.gitignore` change (`.claude/*` + `!.claude/skills/`) that makes skills the only tracked part of `.claude/`. Merged to main in peoplepower/python-core (commit 558a508). diff --git a/pyproject.toml b/pyproject.toml index dad8e61..a58d88e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,7 +7,7 @@ name = "caredaily" description = "CLI and API interface for CareDaily applications." keywords = ["caredaily", "smart-home", "iot", "api-client", "sdk", "cli", "home-automation", "caregiving", "monitoring", "devices"] readme = "README.md" -version = "1.0.2" +version = "1.0.3" requires-python = ">=3.10" license = "Apache-2.0" authors = [ diff --git a/src/caredaily/__init__.py b/src/caredaily/__init__.py index 3f00352..f40531b 100644 --- a/src/caredaily/__init__.py +++ b/src/caredaily/__init__.py @@ -7,7 +7,7 @@ Provides APIs, models, and utilities for interacting with the CareDaily platform. """ -__version__ = "1.0.2" +__version__ = "1.0.3" from .apis import ( AdminDevices, @@ -20,7 +20,6 @@ Billing, BotDeveloper, BotStore, - Challenges, CloudConnectivity, CloudsIntegration, DeveloperTeams, @@ -46,7 +45,6 @@ UserCommunication, UserGroups, Users, - Weather, Websocket, ) from .caredaily import CareDaily @@ -97,14 +95,12 @@ "SystemAndUserProperties", "UserAccounts", "UserCommunication", - "Weather", "Websocket", # Admin APIs "AdminDevices", "AdminLocations", "AdminTags", "Billing", - "Challenges", "Firmware", "Groups", "Narratives", diff --git a/src/caredaily/apis/__init__.py b/src/caredaily/apis/__init__.py index e50f963..8efa07f 100644 --- a/src/caredaily/apis/__init__.py +++ b/src/caredaily/apis/__init__.py @@ -4,7 +4,6 @@ from .admin import ( Billing, - Challenges, Devices as AdminDevices, Firmware, Groups, @@ -37,7 +36,6 @@ SystemAndUserProperties, UserAccounts, UserCommunication, - Weather, Websocket, ) from .bot import ( @@ -69,14 +67,12 @@ "SystemAndUserProperties", "UserAccounts", "UserCommunication", - "Weather", "Websocket", # Admin APIs "AdminDevices", "AdminLocations", "AdminTags", "Billing", - "Challenges", "Firmware", "Groups", "Narratives", diff --git a/src/caredaily/apis/admin/__init__.py b/src/caredaily/apis/admin/__init__.py index ab5cc22..6526f41 100644 --- a/src/caredaily/apis/admin/__init__.py +++ b/src/caredaily/apis/admin/__init__.py @@ -3,7 +3,6 @@ # /// from .billing import Billing -from .challenges import Challenges from .devices import Devices from .firmware import Firmware from .groups import Groups @@ -18,7 +17,6 @@ __all__ = [ "Billing", - "Challenges", "Devices", "Firmware", "Groups", diff --git a/src/caredaily/apis/admin/challenges.py b/src/caredaily/apis/admin/challenges.py deleted file mode 100644 index 6c2ea40..0000000 --- a/src/caredaily/apis/admin/challenges.py +++ /dev/null @@ -1,282 +0,0 @@ -# /// script -# requires-python = ">=3.8" -# dependencies = [ -# "requests", -# ] -# /// - -from typing import Dict - -from ..api import API - -from ...models import ( - APIKeyType, - Result, -) - - -class Challenges(API): - """ - Challenges API for managing organization challenges and participant operations. - - This class provides methods to create, retrieve, update, delete, and manage the status of challenges, as well as retrieve challenge participants. - Supports filtering, template-based creation, and status management for community engagement challenges. - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges - """ - def create_challenge( - self, - organization_id: int, - challenge_data: Dict, - check: bool = None, - parent_id: int = None, - ) -> Result: - """ - Create a challenge from scratch or from a template. - - In a community social network setting, an Engagement Manager may issue challenges - to the community, to help achieve the overall goals of the community. - - Args: - organization_id: Organization ID to create this challenge for - challenge_data: Challenge data as JSON object with 'challenge' key - check: True - Check if an active challenge already exists without creating one. - False - Do not check, just create it (default) - parent_id: Challenge or template ID to copy settings from - - Returns: - Result: API response with challengeId - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges/operation/Create%20a%20Challenge - """ - params = { - "check": check, - "parentId": parent_id, - } - params = {k: v for k, v in params.items() if v is not None} - result: Result = self.adapter.post( - f"/espapi/admin/json/organizations/{organization_id}/challenges", - ep_params=params, - ep_json=challenge_data if challenge_data else None, - ep_headers=self.adapter._get_headers( - api_key=self.adapter._headers.get("ADMIN_KEY"), - key_type=APIKeyType.USER - ), - ) - return result - - def get_challenges( - self, - organization_id: int, - status: int = None, - challenge_id: int = None, - challenge_type: int = None, - search_by: str = None, - parent_id: int = None, - ) -> Result: - """ - View a list of challenges selected by their parameters. - Only admins can see the templates in the search results. - - Args: - organization_id: Organization ID to retrieve challenges for - status: Optional status filter (0=Inactive, 1=Active, 2=Completed) - challenge_id: Retrieve only this challenge - challenge_type: Filter response by challenge types - search_by: Search by name - parent_id: Template ID to filter by - - Returns: - Result: API response with challenges data - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges/operation/Get%20Challenges - """ - params = { - "status": status, - "challengeId": challenge_id, - "challengeType": challenge_type, - "searchBy": search_by, - "parentId": parent_id, - } - params = {k: v for k, v in params.items() if v is not None} - result: Result = self.adapter.get( - f"/espapi/admin/json/organizations/{organization_id}/challenges", - ep_params=params, - ep_headers=self.adapter._get_headers( - {"API_KEY": self.adapter._headers.get("USER_KEY")} - ), - ) - return result - - def update_challenge( - self, - organization_id: int, - challenge_id: int, - challenge_data: Dict, - ) -> Result: - """ - Update a challenge. - - An administrator can modify all template fields except 'template' and 'challengeType'. - - Args: - organization_id: Organization ID to update a challenge within - challenge_id: Challenge ID to update - challenge_data: Challenge data as JSON object with 'challenge' key - - Returns: - Result: API response confirming update - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges/operation/Update%20a%20Challenge - """ - result: Result = self.adapter.put( - f"/espapi/admin/json/organizations/{organization_id}/challenges/{challenge_id}", - ep_json=challenge_data if challenge_data else None, - ep_headers=self.adapter._get_headers( - api_key=self.adapter._headers.get("ADMIN_KEY"), - key_type=APIKeyType.USER - ), - ) - return result - - def delete_challenge( - self, - organization_id: int, - challenge_id: int, - ) -> Result: - """ - Delete a challenge. - - Args: - organization_id: Organization ID - challenge_id: Challenge ID to delete - - Returns: - Result: API response confirming deletion - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges/operation/Delete%20a%20Challenge - """ - result: Result = self.adapter.delete( - f"/espapi/admin/json/organizations/{organization_id}/challenges/{challenge_id}", - ep_headers=self.adapter._get_headers( - api_key=self.adapter._headers.get("ADMIN_KEY"), - key_type=APIKeyType.USER - ), - ) - return result - - def update_challenge_status( - self, - organization_id: int, - challenge_id: int, - status: int, - ) -> Result: - """ - Update challenge status. - - Args: - organization_id: Organization ID to update - challenge_id: Challenge ID to update - status: New status (0=Inactive, 1=Active) - - Returns: - Result: API response confirming status update - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges/operation/Update%20Challenge%20Status - """ - result: Result = self.adapter.put( - f"/espapi/admin/json/organizations/{organization_id}/challenges/{challenge_id}/status/{status}", - ep_headers=self.adapter._get_headers( - api_key=self.adapter._headers.get("ADMIN_KEY"), - key_type=APIKeyType.USER - ), - ) - return result - - def get_challenge_participants( - self, - organization_id: int, - challenge_id: int, - status: int = None, - location_id: int = None, - ) -> Result: - """ - Return invitational challenge participants. - - Only approved members of the given organization and the challenge participants - can call this API. - - Participation statuses: - - 1: Not responded - - 2: Opt-In - - 3: Opt-Out - - Args: - organization_id: Organization ID - challenge_id: Challenge ID to obtain winners for - status: Participation status filter - location_id: Filter the response by location ID - - Returns: - Result: API response with participants data - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges/operation/Get%20Participants - """ - params = { - "status": status, - "locationId": location_id, - } - params = {k: v for k, v in params.items() if v is not None} - result: Result = self.adapter.get( - f"/espapi/admin/json/organizations/{organization_id}/challenges/{challenge_id}/participants", - ep_params=params, - ep_headers=self.adapter._get_headers( - {"API_KEY": self.adapter._headers.get("USER_KEY")} - ), - ) - return result - - def update_challenge_participant_status( - self, - organization_id: int, - challenge_id: int, - status: int, - location_id: int, - ) -> Result: - """ - Update participation status to Opt-In or Opt-Out. - - Only approved members of the given organization and the challenge participants - can update their participation status. - - Args: - organization_id: Organization ID - challenge_id: Challenge ID - status: New participation status (2=Opt-In, 3=Opt-Out) - location_id: Location ID - - Returns: - Result: API response confirming status update - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/admin.html#tag/Challenges/operation/Update%20Status - """ - params = { - "status": status, - "locationId": location_id, - } - result: Result = self.adapter.put( - f"/espapi/admin/json/organizations/{organization_id}/challenges/{challenge_id}/participants", - ep_params=params, - ep_headers=self.adapter._get_headers( - {"API_KEY": self.adapter._headers.get("USER_KEY")} - ), - ) - return result diff --git a/src/caredaily/apis/app/__init__.py b/src/caredaily/apis/app/__init__.py index 6d78057..64c11a9 100644 --- a/src/caredaily/apis/app/__init__.py +++ b/src/caredaily/apis/app/__init__.py @@ -20,7 +20,6 @@ from .system_and_user_properties import SystemAndUserProperties from .user_accounts import UserAccounts from .user_communication import UserCommunication -from .weather import Weather from .websocket import Websocket __all__ = [ @@ -42,6 +41,5 @@ "SystemAndUserProperties", "UserAccounts", "UserCommunication", - "Weather", "Websocket", ] diff --git a/src/caredaily/apis/app/device_types_and_parameters.py b/src/caredaily/apis/app/device_types_and_parameters.py index 30a7877..dbd91de 100644 --- a/src/caredaily/apis/app/device_types_and_parameters.py +++ b/src/caredaily/apis/app/device_types_and_parameters.py @@ -28,8 +28,6 @@ def get_device_types( attribute_name: str = None, attribute_value: str = None, own: bool = None, - simple: bool = None, - organization_id: int = None, ) -> Result: """ Get Device Types. @@ -41,8 +39,6 @@ def get_device_types( attribute_name: Filter by attribute name attribute_value: Filter by attribute value own: Filter by own device types - simple: Return simplified device type information - organization_id: Filter by organization ID Returns: Result: API response with device types list @@ -55,8 +51,6 @@ def get_device_types( "attributeName": attribute_name, "attributeValue": attribute_value, "own": own, - "simple": simple, - "organizationId": organization_id, } params = {k: v for k, v in params.items() if v is not None} result: Result = self.adapter.get( @@ -304,6 +298,7 @@ def add_default_rule( self, device_type: int, rule_id: int, + location_id: int, hidden: bool = None, ) -> Result: """ @@ -318,6 +313,7 @@ def add_default_rule( Args: device_type: The device type ID rule_id: The rule ID + location_id: The rule's location ID hidden: true - A new generated rule will be hidden and a user will not see it. false - A user will see this rule in the list, default @@ -328,6 +324,7 @@ def add_default_rule( https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Products-Management/operation/Add%20Default%20Rule """ params = { + "locationId": location_id, "hidden": hidden, } params = {k: v for k, v in params.items() if v is not None} diff --git a/src/caredaily/apis/app/locations.py b/src/caredaily/apis/app/locations.py index 636c56a..e511dd7 100644 --- a/src/caredaily/apis/app/locations.py +++ b/src/caredaily/apis/app/locations.py @@ -672,6 +672,7 @@ def get_narratives( end_date_ms: int = None, page_marker: str = None, analytic_key: str = None, + escalation_id: int = None, ): """ Get narratives for a location. @@ -692,6 +693,7 @@ def get_narratives( end_date_ms: End date in milliseconds since epoch page_marker: Page marker for pagination analytic_key: Optional analytic API key for bot access + escalation_id: Only return narratives referencing this escalation Returns: Result: API response containing list of narratives @@ -713,6 +715,7 @@ def get_narratives( "startDate": start_date_ms, "endDate": end_date_ms, "pageMarker": page_marker, + "escalationId": escalation_id, } params = {k: v for k, v in params.items() if v is not None} headers = None @@ -742,7 +745,8 @@ def put_narrative( Args: location_id: Location ID to create/update narrative for scope: Narrative scope (user, location, organization) - narrative: Dictionary containing narrative data + narrative: Dictionary containing narrative data. May include an + ``escalationId`` to link the narrative to an escalation. publish: Whether to publish the narrative to subscribers, default is true store: Store a new narrative in the database, default is true. Can be set to False if it is only for publishing. @@ -820,7 +824,139 @@ def delete_a_narrative( ep_headers=headers, ) return result - + + def get_escalations( + self, + location_id: int = None, + organization_id: int = None, + escalation_id: int = None, + start_date: str = None, + end_date: str = None, + status: int | List[int] = None, + escalation_type: int | List[int] = None, + priority: int | List[int] = None, + analytic_key: str = None, + ): + """ + Get escalations matching the search parameters. + + Escalations are significant events (a fall, a call for help, a device + outage, ...) created by bots and referenced by narratives, notifications + and tickets. + + Args: + location_id: Location ID. Required for end users, or if + ``organization_id`` is not provided. + organization_id: Organization ID (admins only). Required if + ``location_id`` is not provided. + escalation_id: Return only this escalation + start_date: Search start date and time. Required if + ``escalation_id`` is not provided. + end_date: Search end date and time + status: Escalation status(es): 1=Open, 2=Confirmed, 3=Resolved, + 4=Cancelled, 5=Expired + escalation_type: Escalation type(s), e.g. 1=Fall detected, + 3=Call for help, 16=Device offline + priority: Priority(ies): 1=Normal, 2=High, 3=Urgent + analytic_key: Optional analytic API key for bot access + + Returns: + Result: API response containing the list of escalations + + Reference: + https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Location-Events/operation/Get%20Escalations + """ + params = { + "locationId": location_id, + "organizationId": organization_id, + "escalationId": escalation_id, + "startDate": start_date, + "endDate": end_date, + "status": status, + "escalationType": escalation_type, + "priority": priority, + } + params = {k: v for k, v in params.items() if v is not None} + headers = None + if analytic_key: + headers = self.adapter._get_headers(analytic_key, APIKeyType.ANALYTIC) + result: Result = self.adapter.get( + "/cloud/json/escalations", + ep_params=params, + ep_headers=headers, + ) + return result + + def create_escalation( + self, + location_id: int, + escalation: Dict, + analytic_key: str = None, + ): + """ + Create an escalation. Bot API key only. + + Args: + location_id: Location ID + escalation: Escalation fields; ``escalationType`` and ``priority`` + are required. Optional: title, description, icon, expiryDate, + eventDate, userId, deviceId, eventSourceType, eventData, + createBotService. + analytic_key: Optional analytic API key for bot access + + Returns: + Result: API response containing the new ``escalationId`` + + Reference: + https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Location-Events/operation/Create%20Escalation + """ + headers = None + if analytic_key: + headers = self.adapter._get_headers(analytic_key, APIKeyType.ANALYTIC) + result: Result = self.adapter.post( + "/cloud/json/escalations", + ep_params={"locationId": location_id}, + ep_json={"escalation": escalation}, + ep_headers=headers, + ) + return result + + def update_escalation( + self, + location_id: int, + escalation_id: int, + escalation: Dict, + analytic_key: str = None, + ): + """ + Update an escalation's status and related fields. + + Args: + location_id: Location ID + escalation_id: Escalation ID to update + escalation: Fields to update: status, confirmationDate, + confirmUserId, resolutionDate, resolveUserId, resolveSourceType. + Confirmation/resolution dates default to now for the + corresponding statuses. + analytic_key: Optional analytic API key for bot access + + Returns: + Result: API response confirming the update + + Reference: + https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Location-Events/operation/Update%20Escalation + """ + headers = None + if analytic_key: + headers = self.adapter._get_headers(analytic_key, APIKeyType.ANALYTIC) + result: Result = self.adapter.put( + "/cloud/json/escalations", + ep_params={"locationId": location_id, "escalationId": escalation_id}, + ep_json={"escalation": escalation}, + ep_headers=headers, + ) + return result + def stream_message( self, scope: str, diff --git a/src/caredaily/apis/app/paid_services.py b/src/caredaily/apis/app/paid_services.py index def2110..5f5f933 100644 --- a/src/caredaily/apis/app/paid_services.py +++ b/src/caredaily/apis/app/paid_services.py @@ -77,7 +77,6 @@ def get_location_service_plans( location_id: int, status: int = None, user_plan_id: int = None, - get_card: bool = None, user_id: int = None, ) -> Result: """ @@ -89,7 +88,6 @@ def get_location_service_plans( location_id: Get plan on this location status: Service plan status filter user_plan_id: Get specific service plan by ID - get_card: Retrieve payment card information from the payment provider user_id: Get plan by this user. Used by organization administrators. Returns: @@ -102,7 +100,6 @@ def get_location_service_plans( "locationId": location_id, "status": status, "userPlanId": user_plan_id, - "getCard": get_card, "userId": user_id, } params = {k: v for k, v in params.items() if v is not None} @@ -366,7 +363,8 @@ def assign_services_to_group_of_users( Args: service_plan_id: The Service Plan ID to assign - assignment_data: Assignment data as JSON object with 'locations' array containing location and user IDs + assignment_data: Assignment data as JSON object with 'locations' array of + {'locationId': ..., 'userId': ...} entries (locationId required per entry) location_id: Location ID to assign the service plan (optional if in assignment_data) organization_id: Organization ID. Required if called by an organization administrator end_date: The end date of the service plan diff --git a/src/caredaily/apis/app/user_accounts.py b/src/caredaily/apis/app/user_accounts.py index 09e858a..2a4561a 100644 --- a/src/caredaily/apis/app/user_accounts.py +++ b/src/caredaily/apis/app/user_accounts.py @@ -531,90 +531,3 @@ def delete_user_tag( """ result: Result = self.adapter.delete(f"/cloud/json/usertags/{tag}") return result - - def put_user_code( - self, - name: str, - code: str = None, - location_id: int = None, - type: int = None, - device_id: str = None, - set_expiry: bool = None, - verify: bool = None, - ): - """ - Create or update a user code. - - User codes are used for various purposes like device pairing, access codes, etc. - - Args: - name: Code name/identifier - code: The actual code value - location_id: Optional location ID to associate with the code - type: Code type identifier - device_id: Optional device ID to associate with the code - set_expiry: Whether to set an expiration time - verify: Whether to verify the code immediately - - Returns: - Result: API response with code creation/update result - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/cloud.html#put-user-code - """ - params = { - "name": name, - "code": code, - "locationId": location_id, - "type": type, - "deviceId": device_id, - "setExpiry": set_expiry, - "verify": verify, - } - params = {k: v for k, v in params.items() if v is not None} - result: Result = self.adapter.put( - "/cloud/json/userCodes", ep_params=params - ) - return result - - def get_user_codes(self): - """ - Get all user codes for the current user. - - Returns: - Result: API response containing list of user codes with their properties - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/cloud.html#get-user-codes - """ - result: Result = self.adapter.get("/cloud/json/userCodes") - return result - - def delete_user_code( - self, - name: str, - location_id: int = None, - ): - """ - Delete a user code. - - Args: - name: Code name to delete - location_id: Optional location ID to scope the deletion - - Returns: - Result: API response confirming code deletion - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/cloud.html#delete-user-code - """ - params = { - "name": name, - "locationId": location_id, - } - params = {k: v for k, v in params.items() if v is not None} - result: Result = self.adapter.delete( - "/cloud/json/userCodes", ep_params=params - ) - return result - diff --git a/src/caredaily/apis/app/weather.py b/src/caredaily/apis/app/weather.py deleted file mode 100644 index 68bf12b..0000000 --- a/src/caredaily/apis/app/weather.py +++ /dev/null @@ -1,154 +0,0 @@ -# /// script -# requires-python = ">=3.8" -# dependencies = [ -# "requests", -# ] -# /// - -import json -from typing import Dict, List, Optional - -from ...models import ( - APIKeyType, - Cloud, - MQTT, - Result, - Server, - ServerType, - SignatureAlgorithm, -) -from ..api import API - - -class Weather(API): - def get_weather( - self, - location_id: int, - units: str = None, - hours: int = None, - ) -> Result: - """ - Get Weather Forecast for a Location. - - Retrieve weather forecast for a location. - - Args: - location_id: Location ID (required) - units: Units for measurements (e = English, m = Metric, h = Hybrid, s = Metric SI) - hours: Forecast depth in hours (6, 12, 24, 48). Default is 24. - - Returns: - Result: API response with weather forecast - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Weather/operation/Get%20Forecast%20by%20Location - """ - params = { - "units": units, - "hours": hours, - } - params = {k: v for k, v in params.items() if v is not None} - result: Result = self.adapter.get( - f"/cloud/json/weather/forecast/location/{location_id}", - ep_params=params, - ) - return result - - def get_weather_current_by_location( - self, - location_id: int, - units: Optional[str] = None, - ) -> Result: - """ - Get Current Weather by Location. - - Retrieve current weather conditions by the location address. - - Args: - location_id: ID of location (required) - units: Units for measurements (e = English, m = Metric, h = Hybrid, s = Metric SI) - - Returns: - Result: API response with current weather data - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Weather/operation/Get%20Current%20Weather%20by%20Location - """ - params = {} - if units is not None: - params["units"] = units - result: Result = self.adapter.get( - f"/cloud/json/weather/current/location/{location_id}", - ep_params=params if params else None, - ) - return result - - def get_weather_current_by_geocode( - self, - latitude: str, - longitude: str, - units: Optional[str] = None, - ) -> Result: - """ - Get Current Weather by Geocode. - - Retrieve current weather conditions at certain point by latitude and longitude. - - Args: - latitude: Latitude (required) - longitude: Longitude (required) - units: Units for measurements (e = English, m = Metric, h = Hybrid, s = Metric SI) - - Returns: - Result: API response with current weather data - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Weather/operation/Get%20Current%20Weather%20by%20Geocode - """ - params = {} - if units is not None: - params["units"] = units - result: Result = self.adapter.get( - f"/cloud/json/weather/current/geocode/{latitude}/{longitude}", - ep_params=params if params else None, - ) - return result - - def get_weather_forecast_by_geocode( - self, - latitude: str, - longitude: str, - units: Optional[str] = None, - hours: Optional[int] = None, - organization_id: Optional[int] = None, - ) -> Result: - """ - Get Forecast by Geocode. - - Retrieve weather forecast at certain point by latitude and longitude. - - Args: - latitude: Latitude (required) - longitude: Longitude (required) - units: Units for measurements (e = English, m = Metric, h = Hybrid, s = Metric SI) - hours: Forecast depth in hours (6, 12, 24, 48). Default is 24. - organization_id: For specific organization. Used by administrator only. - - Returns: - Result: API response with weather forecast - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Weather/operation/Get%20Forecast%20by%20Geocode - """ - params = {} - if units is not None: - params["units"] = units - if hours is not None: - params["hours"] = hours - if organization_id is not None: - params["organizationId"] = organization_id - result: Result = self.adapter.get( - f"/cloud/json/weather/forecast/geocode/{latitude}/{longitude}", - ep_params=params if params else None, - ) - return result diff --git a/src/caredaily/apis/bot/analytic.py b/src/caredaily/apis/bot/analytic.py index cef69c1..2a6d64e 100644 --- a/src/caredaily/apis/bot/analytic.py +++ b/src/caredaily/apis/bot/analytic.py @@ -510,6 +510,7 @@ def ask_questions( - questionWeight: Question weight - responseType: Response type - responseOptions: List of response option objects + - permissions: List of integer permission levels Returns: Result: API response with created questions @@ -1449,44 +1450,3 @@ def execute_cli( ep_json=cli_data, ) return result - - def get_challenge_participants( - self, - challenge_id: int, - status: Optional[int] = None, - location_id: Optional[int] = None, - get_devices: Optional[bool] = None, - device_category: Optional[int] = None, - ) -> Result: - """ - Get Participants. - - Return invitational challenge participants. - - Args: - challenge_id: Challenge ID to obtain participants for (required) - status: Participation status filter - location_id: Filter the response by location ID - get_devices: Return devices as well - device_category: Filter devices by a type category - - Returns: - Result: API response with challenge participants - - Reference: - https://app.peoplepowerco.com/cloud/apidocs/bots.html#tag/Bot-Challenge-APIs/operation/Get%20Participants - """ - params = {} - if status is not None: - params["status"] = status - if location_id is not None: - params["locationId"] = location_id - if get_devices is not None: - params["getDevices"] = get_devices - if device_category is not None: - params["deviceCategory"] = device_category - result: Result = self.adapter.get( - f"/espapi/analytic/admin/challenges/{challenge_id}/participants", - ep_params=params if params else None, - ) - return result diff --git a/src/caredaily/caredaily.py b/src/caredaily/caredaily.py index 2f94e56..8facd57 100644 --- a/src/caredaily/caredaily.py +++ b/src/caredaily/caredaily.py @@ -24,7 +24,6 @@ Billing, BotDeveloper, BotStore, - Challenges, CloudConnectivity, CloudsIntegration, DeveloperTeams, @@ -50,7 +49,6 @@ UserCommunication, UserGroups, Users, - Weather, Websocket, ) from .exceptions import CareDailyException @@ -198,8 +196,6 @@ def app_api(self, type: type): return ProfessionalMonitoring(self._config) if type == EnergyManagement: return EnergyManagement(self._config) - if type == Weather: - return Weather(self._config) if type == DeviceTypesAndParameters: return DeviceTypesAndParameters(self._config) if type == CloudsIntegration: @@ -228,8 +224,6 @@ def admin_api(self, type: type): return AdminDevices(self._config) if type == AdminLocations: return AdminLocations(self._config) - if type == Challenges: - return Challenges(self._config) if type == AdminTags: return AdminTags(self._config) if type == Narratives: diff --git a/tests/caredaily/apis/admin/test_challenges.py b/tests/caredaily/apis/admin/test_challenges.py deleted file mode 100644 index f980f0c..0000000 --- a/tests/caredaily/apis/admin/test_challenges.py +++ /dev/null @@ -1,137 +0,0 @@ -import unittest -from unittest.mock import MagicMock - -from caredaily.apis.admin import Challenges - - -class TestChallenges(unittest.TestCase): - def setUp(self): - self.challenges = Challenges() - self.mock_adapter = MagicMock() - self.challenges.adapter = self.mock_adapter - self.mock_adapter._headers = {'ADMIN_KEY': 'admin_key', 'USER_KEY': 'user_key'} - self.mock_adapter._get_headers = MagicMock(return_value={'API_KEY': 'admin_key'}) - - def test_create_challenge_success(self): - challenge_data = {'challenge': {'name': 'Test Challenge'}} - self.mock_adapter.post.return_value = {'challengeId': 1} - result = self.challenges.create_challenge( - organization_id=123, - challenge_data=challenge_data - ) - self.mock_adapter.post.assert_called_once() - args, kwargs = self.mock_adapter.post.call_args - self.assertEqual(kwargs['ep_json'], challenge_data) - self.assertEqual(result, {'challengeId': 1}) - - def test_create_challenge_with_check_and_parent(self): - challenge_data = {'challenge': {'name': 'Test Challenge'}} - self.mock_adapter.post.return_value = {'challengeId': 1} - self.challenges.create_challenge( - organization_id=123, - challenge_data=challenge_data, - check=True, - parent_id=5 - ) - args, kwargs = self.mock_adapter.post.call_args - self.assertEqual(kwargs['ep_params']['check'], True) - self.assertEqual(kwargs['ep_params']['parentId'], 5) - - def test_get_challenges_success(self): - self.mock_adapter.get.return_value = {'challenges': []} - self.mock_adapter._get_headers = MagicMock(return_value={'API_KEY': 'user_key'}) - result = self.challenges.get_challenges(organization_id=123) - self.mock_adapter.get.assert_called_once() - args, kwargs = self.mock_adapter.get.call_args - self.assertEqual(kwargs['ep_params'], {}) - self.assertEqual(result, {'challenges': []}) - - def test_get_challenges_with_all_filters(self): - self.mock_adapter.get.return_value = {'challenges': []} - self.mock_adapter._get_headers = MagicMock(return_value={'API_KEY': 'user_key'}) - self.challenges.get_challenges( - organization_id=123, - status=1, - challenge_id=5, - challenge_type=2, - search_by='test', - parent_id=10 - ) - args, kwargs = self.mock_adapter.get.call_args - self.assertEqual(kwargs['ep_params']['status'], 1) - self.assertEqual(kwargs['ep_params']['challengeId'], 5) - self.assertEqual(kwargs['ep_params']['challengeType'], 2) - self.assertEqual(kwargs['ep_params']['searchBy'], 'test') - self.assertEqual(kwargs['ep_params']['parentId'], 10) - - def test_update_challenge_success(self): - challenge_data = {'challenge': {'name': 'Updated Challenge'}} - self.mock_adapter.put.return_value = {'status': 'ok'} - result = self.challenges.update_challenge( - organization_id=123, - challenge_id=1, - challenge_data=challenge_data - ) - self.mock_adapter.put.assert_called_once() - args, kwargs = self.mock_adapter.put.call_args - self.assertEqual(kwargs['ep_json'], challenge_data) - self.assertEqual(result, {'status': 'ok'}) - - def test_delete_challenge_success(self): - self.mock_adapter.delete.return_value = {'status': 'ok'} - result = self.challenges.delete_challenge( - organization_id=123, - challenge_id=1 - ) - self.mock_adapter.delete.assert_called_once() - self.assertEqual(result, {'status': 'ok'}) - - def test_update_challenge_status_success(self): - self.mock_adapter.put.return_value = {'status': 'ok'} - result = self.challenges.update_challenge_status( - organization_id=123, - challenge_id=1, - status=1 - ) - self.mock_adapter.put.assert_called_once() - self.assertEqual(result, {'status': 'ok'}) - - def test_get_challenge_participants_success(self): - self.mock_adapter.get.return_value = {'participants': []} - self.mock_adapter._get_headers = MagicMock(return_value={'API_KEY': 'user_key'}) - result = self.challenges.get_challenge_participants( - organization_id=123, - challenge_id=1 - ) - self.mock_adapter.get.assert_called_once() - args, kwargs = self.mock_adapter.get.call_args - self.assertEqual(kwargs['ep_params'], {}) - self.assertEqual(result, {'participants': []}) - - def test_get_challenge_participants_with_filters(self): - self.mock_adapter.get.return_value = {'participants': []} - self.mock_adapter._get_headers = MagicMock(return_value={'API_KEY': 'user_key'}) - self.challenges.get_challenge_participants( - organization_id=123, - challenge_id=1, - status=2, - location_id=10 - ) - args, kwargs = self.mock_adapter.get.call_args - self.assertEqual(kwargs['ep_params']['status'], 2) - self.assertEqual(kwargs['ep_params']['locationId'], 10) - - def test_update_challenge_participant_status_success(self): - self.mock_adapter.put.return_value = {'resultCode': 0} - self.mock_adapter._get_headers = MagicMock(return_value={'API_KEY': 'user_key'}) - result = self.challenges.update_challenge_participant_status( - organization_id=123, - challenge_id=1, - status=2, - location_id=10 - ) - self.mock_adapter.put.assert_called_once() - args, kwargs = self.mock_adapter.put.call_args - self.assertEqual(kwargs['ep_params']['status'], 2) - self.assertEqual(kwargs['ep_params']['locationId'], 10) - self.assertEqual(result, {'resultCode': 0}) diff --git a/tests/caredaily/apis/app/test_device_types_and_parameters.py b/tests/caredaily/apis/app/test_device_types_and_parameters.py index 3e38ab0..a10a6de 100644 --- a/tests/caredaily/apis/app/test_device_types_and_parameters.py +++ b/tests/caredaily/apis/app/test_device_types_and_parameters.py @@ -21,13 +21,13 @@ def test_get_device_types_with_filters(self): attribute_name='test_attr', attribute_value='test_value', own=True, - simple=False, - organization_id=123 ) args, kwargs = self.mock_adapter.get.call_args self.assertEqual(kwargs['ep_params']['deviceType'], 1) self.assertEqual(kwargs['ep_params']['attributeName'], 'test_attr') - self.assertEqual(kwargs['ep_params']['organizationId'], 123) + self.assertEqual(kwargs['ep_params']['own'], True) + self.assertNotIn('simple', kwargs['ep_params']) + self.assertNotIn('organizationId', kwargs['ep_params']) def test_get_device_type_attributes(self): device_type = 1 @@ -131,17 +131,20 @@ def test_get_default_rules_with_details(self): def test_add_default_rule(self): self.mock_adapter.post.return_value = {'added': True} - result = self.dtp.add_default_rule(device_type=1, rule_id=10) + result = self.dtp.add_default_rule(device_type=1, rule_id=10, location_id=5) self.mock_adapter.post.assert_called_once() args, kwargs = self.mock_adapter.post.call_args self.assertEqual(args[0], '/cloud/json/deviceType/1/rules/10') + self.assertEqual(kwargs['ep_params'], {'locationId': 5}) self.assertEqual(result, {'added': True}) def test_add_default_rule_with_hidden(self): self.mock_adapter.post.return_value = {'added': True} - result = self.dtp.add_default_rule(device_type=1, rule_id=10, hidden=True) + result = self.dtp.add_default_rule( + device_type=1, rule_id=10, location_id=5, hidden=True + ) args, kwargs = self.mock_adapter.post.call_args - self.assertEqual(kwargs['ep_params']['hidden'], True) + self.assertEqual(kwargs['ep_params'], {'locationId': 5, 'hidden': True}) def test_delete_default_rule(self): self.mock_adapter.delete.return_value = {'deleted': True} diff --git a/tests/caredaily/apis/app/test_locations.py b/tests/caredaily/apis/app/test_locations.py index 79ff69e..b416ec1 100644 --- a/tests/caredaily/apis/app/test_locations.py +++ b/tests/caredaily/apis/app/test_locations.py @@ -203,6 +203,73 @@ def test_get_narratives_with_analytic_key(self): self.mock_adapter._get_headers.assert_called_once_with('key', APIKeyType.ANALYTIC) self.assertEqual(result, 'narratives-result') + def test_get_narratives_by_escalation(self): + self.mock_adapter.get.return_value = 'narratives-result' + self.loc.get_narratives(location_id=1, row_count=10, escalation_id=456) + args, kwargs = self.mock_adapter.get.call_args + self.assertEqual(kwargs['ep_params']['escalationId'], 456) + + def test_get_escalations(self): + self.mock_adapter.get.return_value = 'escalations-result' + result = self.loc.get_escalations( + location_id=1, start_date='2026-09-10T00:00:00Z', status=[1, 2] + ) + args, kwargs = self.mock_adapter.get.call_args + self.assertEqual(args[0], '/cloud/json/escalations') + self.assertEqual( + kwargs['ep_params'], + {'locationId': 1, 'startDate': '2026-09-10T00:00:00Z', 'status': [1, 2]}, + ) + self.assertIsNone(kwargs['ep_headers']) + self.assertEqual(result, 'escalations-result') + + def test_get_escalations_by_organization_with_analytic_key(self): + self.mock_adapter._get_headers.return_value = {'API_KEY': 'analytic_key'} + self.mock_adapter.get.return_value = 'result' + self.loc.get_escalations( + organization_id=7, escalation_id=456, escalation_type=1, priority=3, + end_date='2026-09-11', analytic_key='key', + ) + args, kwargs = self.mock_adapter.get.call_args + self.assertEqual( + kwargs['ep_params'], + {'organizationId': 7, 'escalationId': 456, 'endDate': '2026-09-11', + 'escalationType': 1, 'priority': 3}, + ) + self.mock_adapter._get_headers.assert_called_once_with('key', APIKeyType.ANALYTIC) + self.assertEqual(kwargs['ep_headers'], {'API_KEY': 'analytic_key'}) + + def test_create_escalation(self): + escalation = {'escalationType': 1, 'priority': 3, 'title': 'Fall'} + self.mock_adapter.post.return_value = 'create-result' + result = self.loc.create_escalation(location_id=1, escalation=escalation) + args, kwargs = self.mock_adapter.post.call_args + self.assertEqual(args[0], '/cloud/json/escalations') + self.assertEqual(kwargs['ep_params'], {'locationId': 1}) + self.assertEqual(kwargs['ep_json'], {'escalation': escalation}) + self.assertIsNone(kwargs['ep_headers']) + self.assertEqual(result, 'create-result') + + def test_create_escalation_with_analytic_key(self): + self.mock_adapter._get_headers.return_value = {'API_KEY': 'analytic_key'} + self.loc.create_escalation( + location_id=1, escalation={'escalationType': 1, 'priority': 1}, + analytic_key='key', + ) + self.mock_adapter._get_headers.assert_called_once_with('key', APIKeyType.ANALYTIC) + + def test_update_escalation(self): + escalation = {'status': 3, 'resolveUserId': 123} + self.mock_adapter.put.return_value = 'update-result' + result = self.loc.update_escalation( + location_id=1, escalation_id=456, escalation=escalation + ) + args, kwargs = self.mock_adapter.put.call_args + self.assertEqual(args[0], '/cloud/json/escalations') + self.assertEqual(kwargs['ep_params'], {'locationId': 1, 'escalationId': 456}) + self.assertEqual(kwargs['ep_json'], {'escalation': escalation}) + self.assertEqual(result, 'update-result') + def test_put_narrative(self): narrative_data = {'text': 'Test narrative'} self.mock_adapter.put.return_value = 'put-narrative-result' diff --git a/tests/caredaily/apis/app/test_paid_services.py b/tests/caredaily/apis/app/test_paid_services.py index 52a5464..9038c6d 100644 --- a/tests/caredaily/apis/app/test_paid_services.py +++ b/tests/caredaily/apis/app/test_paid_services.py @@ -94,13 +94,12 @@ def test_get_location_service_plans_with_all_params(self): location_id=123, status=1, user_plan_id=10, - get_card=True, user_id=456 ) args, kwargs = self.mock_adapter.get.call_args self.assertEqual(kwargs['ep_params']['status'], 1) self.assertEqual(kwargs['ep_params']['userPlanId'], 10) - self.assertEqual(kwargs['ep_params']['getCard'], True) + self.assertNotIn('getCard', kwargs['ep_params']) self.assertEqual(kwargs['ep_params']['userId'], 456) def test_post_an_apple_purchase_receipt_with_params(self): diff --git a/tests/caredaily/apis/app/test_user_accounts.py b/tests/caredaily/apis/app/test_user_accounts.py index aa97121..8079045 100644 --- a/tests/caredaily/apis/app/test_user_accounts.py +++ b/tests/caredaily/apis/app/test_user_accounts.py @@ -208,49 +208,6 @@ def test_delete_user_tag(self): self.assertEqual(args[0], '/cloud/json/usertags/test_tag') self.assertEqual(result, 'delete-tag-result') - def test_put_user_code(self): - self.mock_adapter.put.return_value = 'code-result' - result = self.ua.put_user_code( - name='test_code', - code='1234', - location_id=1, - type=2 - ) - self.mock_adapter.put.assert_called_once() - args, kwargs = self.mock_adapter.put.call_args - self.assertEqual(args[0], '/cloud/json/userCodes') - self.assertEqual(kwargs['ep_params']['name'], 'test_code') - self.assertEqual(kwargs['ep_params']['code'], '1234') - self.assertEqual(kwargs['ep_params']['locationId'], 1) - self.assertEqual(kwargs['ep_params']['type'], 2) - self.assertEqual(result, 'code-result') - - def test_get_user_codes(self): - self.mock_adapter.get.return_value = 'codes-result' - result = self.ua.get_user_codes() - self.mock_adapter.get.assert_called_once() - args, kwargs = self.mock_adapter.get.call_args - self.assertEqual(args[0], '/cloud/json/userCodes') - self.assertEqual(result, 'codes-result') - - def test_delete_user_code(self): - self.mock_adapter.delete.return_value = 'delete-code-result' - result = self.ua.delete_user_code(name='test_code', location_id=1) - self.mock_adapter.delete.assert_called_once() - args, kwargs = self.mock_adapter.delete.call_args - self.assertEqual(args[0], '/cloud/json/userCodes') - self.assertEqual(kwargs['ep_params']['name'], 'test_code') - self.assertEqual(kwargs['ep_params']['locationId'], 1) - self.assertEqual(result, 'delete-code-result') - - def test_delete_user_code_no_location(self): - self.mock_adapter.delete.return_value = 'delete-code-result' - result = self.ua.delete_user_code(name='test_code') - args, kwargs = self.mock_adapter.delete.call_args - self.assertEqual(kwargs['ep_params']['name'], 'test_code') - self.assertNotIn('locationId', kwargs['ep_params']) - self.assertEqual(result, 'delete-code-result') - def test_get_new_password(self): """Test Case ID: TC-UserAccounts-001 Title: Get New Password (Recover Password) diff --git a/tests/caredaily/apis/app/test_weather.py b/tests/caredaily/apis/app/test_weather.py deleted file mode 100644 index 239ed2f..0000000 --- a/tests/caredaily/apis/app/test_weather.py +++ /dev/null @@ -1,200 +0,0 @@ -import unittest -from unittest.mock import MagicMock -from caredaily.apis.app import Weather - -class TestWeather(unittest.TestCase): - def setUp(self): - self.weather = Weather() - self.mock_adapter = MagicMock() - self.weather.adapter = self.mock_adapter - - def test_get_weather_no_params(self): - """Test get_weather with only required location_id""" - location_id = 1 - self.mock_adapter.get.return_value = 'weather-result' - result = self.weather.get_weather(location_id=location_id) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/location/{location_id}', - ep_params={} - ) - self.assertEqual(result, 'weather-result') - - def test_get_weather_with_units(self): - """Test get_weather with units parameter""" - location_id = 1 - units = 'm' - self.mock_adapter.get.return_value = 'weather-result' - result = self.weather.get_weather(location_id=location_id, units=units) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/location/{location_id}', - ep_params={'units': units} - ) - self.assertEqual(result, 'weather-result') - - def test_get_weather_with_hours(self): - """Test get_weather with hours parameter""" - location_id = 1 - hours = 48 - self.mock_adapter.get.return_value = 'weather-result' - result = self.weather.get_weather(location_id=location_id, hours=hours) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/location/{location_id}', - ep_params={'hours': hours} - ) - self.assertEqual(result, 'weather-result') - - def test_get_weather_with_all_params(self): - """Test get_weather with all optional parameters""" - location_id = 1 - units = 'e' - hours = 24 - self.mock_adapter.get.return_value = 'weather-result' - result = self.weather.get_weather(location_id=location_id, units=units, hours=hours) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/location/{location_id}', - ep_params={'units': units, 'hours': hours} - ) - self.assertEqual(result, 'weather-result') - - def test_get_weather_current_by_location_no_units(self): - """Test get_weather_current_by_location without units""" - location_id = 123 - self.mock_adapter.get.return_value = 'current-weather-result' - result = self.weather.get_weather_current_by_location(location_id=location_id) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/current/location/{location_id}', - ep_params=None - ) - self.assertEqual(result, 'current-weather-result') - - def test_get_weather_current_by_location_with_units(self): - """Test get_weather_current_by_location with units""" - location_id = 123 - units = 'm' - self.mock_adapter.get.return_value = 'current-weather-result' - result = self.weather.get_weather_current_by_location(location_id=location_id, units=units) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/current/location/{location_id}', - ep_params={'units': units} - ) - self.assertEqual(result, 'current-weather-result') - - def test_get_weather_current_by_geocode_no_units(self): - """Test get_weather_current_by_geocode without units""" - latitude = '37.7749' - longitude = '-122.4194' - self.mock_adapter.get.return_value = 'geocode-weather-result' - result = self.weather.get_weather_current_by_geocode(latitude=latitude, longitude=longitude) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/current/geocode/{latitude}/{longitude}', - ep_params=None - ) - self.assertEqual(result, 'geocode-weather-result') - - def test_get_weather_current_by_geocode_with_units(self): - """Test get_weather_current_by_geocode with units""" - latitude = '37.7749' - longitude = '-122.4194' - units = 'h' - self.mock_adapter.get.return_value = 'geocode-weather-result' - result = self.weather.get_weather_current_by_geocode( - latitude=latitude, - longitude=longitude, - units=units - ) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/current/geocode/{latitude}/{longitude}', - ep_params={'units': units} - ) - self.assertEqual(result, 'geocode-weather-result') - - def test_get_weather_forecast_by_geocode_no_params(self): - """Test get_weather_forecast_by_geocode with only required parameters""" - latitude = '40.7128' - longitude = '-74.0060' - self.mock_adapter.get.return_value = 'forecast-result' - result = self.weather.get_weather_forecast_by_geocode( - latitude=latitude, - longitude=longitude - ) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/geocode/{latitude}/{longitude}', - ep_params=None - ) - self.assertEqual(result, 'forecast-result') - - def test_get_weather_forecast_by_geocode_with_units(self): - """Test get_weather_forecast_by_geocode with units""" - latitude = '40.7128' - longitude = '-74.0060' - units = 's' - self.mock_adapter.get.return_value = 'forecast-result' - result = self.weather.get_weather_forecast_by_geocode( - latitude=latitude, - longitude=longitude, - units=units - ) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/geocode/{latitude}/{longitude}', - ep_params={'units': units} - ) - self.assertEqual(result, 'forecast-result') - - def test_get_weather_forecast_by_geocode_with_hours(self): - """Test get_weather_forecast_by_geocode with hours""" - latitude = '40.7128' - longitude = '-74.0060' - hours = 12 - self.mock_adapter.get.return_value = 'forecast-result' - result = self.weather.get_weather_forecast_by_geocode( - latitude=latitude, - longitude=longitude, - hours=hours - ) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/geocode/{latitude}/{longitude}', - ep_params={'hours': hours} - ) - self.assertEqual(result, 'forecast-result') - - def test_get_weather_forecast_by_geocode_with_organization_id(self): - """Test get_weather_forecast_by_geocode with organization_id""" - latitude = '40.7128' - longitude = '-74.0060' - organization_id = 456 - self.mock_adapter.get.return_value = 'forecast-result' - result = self.weather.get_weather_forecast_by_geocode( - latitude=latitude, - longitude=longitude, - organization_id=organization_id - ) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/geocode/{latitude}/{longitude}', - ep_params={'organizationId': organization_id} - ) - self.assertEqual(result, 'forecast-result') - - def test_get_weather_forecast_by_geocode_with_all_params(self): - """Test get_weather_forecast_by_geocode with all optional parameters""" - latitude = '40.7128' - longitude = '-74.0060' - units = 'm' - hours = 48 - organization_id = 789 - self.mock_adapter.get.return_value = 'forecast-result' - result = self.weather.get_weather_forecast_by_geocode( - latitude=latitude, - longitude=longitude, - units=units, - hours=hours, - organization_id=organization_id - ) - self.mock_adapter.get.assert_called_once_with( - f'/cloud/json/weather/forecast/geocode/{latitude}/{longitude}', - ep_params={ - 'units': units, - 'hours': hours, - 'organizationId': organization_id - } - ) - self.assertEqual(result, 'forecast-result') diff --git a/tests/caredaily/apis/bot/test_analytic.py b/tests/caredaily/apis/bot/test_analytic.py index 6e8ae06..7591b3a 100644 --- a/tests/caredaily/apis/bot/test_analytic.py +++ b/tests/caredaily/apis/bot/test_analytic.py @@ -453,20 +453,6 @@ def test_execute_cli_success(self): self.assertEqual(kwargs['ep_params']['initialize'], 'true') self.assertEqual(result, {'resultCode': 0}) - def test_get_challenge_participants_success(self): - self.mock_adapter.get.return_value = {'locations': []} - result = self.analytic.get_challenge_participants(challenge_id=1) - self.mock_adapter.get.assert_called_once() - self.assertEqual(result, {'locations': []}) - - def test_get_challenge_participants_with_filters(self): - self.mock_adapter.get.return_value = {'locations': []} - self.analytic.get_challenge_participants(challenge_id=1, status=2, location_id=123, get_devices=True) - args, kwargs = self.mock_adapter.get.call_args - self.assertEqual(kwargs['ep_params']['status'], 2) - self.assertEqual(kwargs['ep_params']['locationId'], 123) - self.assertEqual(kwargs['ep_params']['getDevices'], True) - def test_get_device_parameters_with_historical(self): """Test Case ID: TC-Analytic-001 Title: Get Device Parameters with Historical Query Parameters diff --git a/tests/caredaily/test_caredaily.py b/tests/caredaily/test_caredaily.py index 5c4740f..b99372d 100644 --- a/tests/caredaily/test_caredaily.py +++ b/tests/caredaily/test_caredaily.py @@ -15,7 +15,6 @@ Billing, BotDeveloper, BotStore, - Challenges, CloudConnectivity, CloudsIntegration, DeveloperTeams, @@ -41,7 +40,6 @@ UserCommunication, UserGroups, Users, - Weather, Websocket, ) from caredaily.caredaily import CareDaily @@ -372,7 +370,6 @@ def test_app_api_all_types(self, mock_home=None): (PaidServices, PaidServices), (ProfessionalMonitoring, ProfessionalMonitoring), (EnergyManagement, EnergyManagement), - (Weather, Weather), (DeviceTypesAndParameters, DeviceTypesAndParameters), (CloudsIntegration, CloudsIntegration), (RAG, RAG), @@ -407,7 +404,6 @@ def test_admin_api_all_types(self, mock_home=None): (UserGroups, UserGroups), (AdminDevices, AdminDevices), (AdminLocations, AdminLocations), - (Challenges, Challenges), (AdminTags, AdminTags), (Narratives, Narratives), (Billing, Billing), From 19d78d3c1690559a93232b72bf87ce07de69117f Mon Sep 17 00:00:00 2001 From: Destry Teeter Date: Mon, 5 Oct 2026 11:38:37 -0700 Subject: [PATCH 2/2] Fix pre-existing CI failures (lint and Python 3.10 tests) - ruff check --fix src/: sort imports and drop unused imports (114 fixes) - Devices.update_location_device: remove an unused postId params dict; the v65 spec defines only the locationId/deviceId path params - CLI configure tests: patch the configure module object directly. caredaily.cli re-exports the `configure` click group under the module's name, so on Python 3.10 the dotted patch target resolved to the group. Co-Authored-By: Claude Opus 5.5 (1M context) --- src/caredaily/__init__.py | 2 +- src/caredaily/apis/admin/billing.py | 4 +-- src/caredaily/apis/admin/devices.py | 3 +- src/caredaily/apis/admin/firmware.py | 7 ++--- src/caredaily/apis/admin/groups.py | 3 +- src/caredaily/apis/admin/locations.py | 3 +- src/caredaily/apis/admin/narratives.py | 3 +- src/caredaily/apis/admin/organizations.py | 3 +- src/caredaily/apis/admin/reports.py | 7 ++--- src/caredaily/apis/admin/tags.py | 3 +- src/caredaily/apis/admin/user_groups.py | 5 ++-- src/caredaily/apis/admin/users.py | 5 ++-- src/caredaily/apis/app/__init__.py | 2 +- src/caredaily/apis/app/app_files.py | 8 ------ src/caredaily/apis/app/cloud_connectivity.py | 7 ----- src/caredaily/apis/app/clouds_integration.py | 9 +----- src/caredaily/apis/app/device_measurements.py | 7 +---- src/caredaily/apis/app/devices.py | 9 ------ src/caredaily/apis/app/energy_management.py | 9 +----- src/caredaily/apis/app/locations.py | 6 +--- .../apis/app/professional_monitoring.py | 9 +----- .../apis/app/system_and_user_properties.py | 9 +----- src/caredaily/apis/app/user_accounts.py | 9 +----- src/caredaily/apis/app/user_communication.py | 3 +- src/caredaily/apis/bot/analytic.py | 3 +- src/caredaily/apis/bot/bot_developer.py | 2 +- src/caredaily/apis/bot/bot_store.py | 1 + src/caredaily/apis/bot/developer_teams.py | 6 ---- src/caredaily/apis/bot/execution.py | 4 +-- src/caredaily/caredaily.py | 4 +-- src/caredaily/models.py | 2 +- tests/caredaily/cli/test_cli_configure.py | 28 +++++++++++-------- 32 files changed, 51 insertions(+), 134 deletions(-) diff --git a/src/caredaily/__init__.py b/src/caredaily/__init__.py index f40531b..08d5401 100644 --- a/src/caredaily/__init__.py +++ b/src/caredaily/__init__.py @@ -51,7 +51,6 @@ from .exceptions import CareDailyException from .models import ( APIKeyType, - SignatureAlgorithm, Cloud, MQTT, PythonRuntime, @@ -59,6 +58,7 @@ ResultCode, Server, ServerType, + SignatureAlgorithm, TimeZone, ) diff --git a/src/caredaily/apis/admin/billing.py b/src/caredaily/apis/admin/billing.py index cbb883c..19aaa72 100644 --- a/src/caredaily/apis/admin/billing.py +++ b/src/caredaily/apis/admin/billing.py @@ -5,15 +5,13 @@ # ] # /// -import json from typing import Dict -from ..api import API - from ...models import ( APIKeyType, Result, ) +from ..api import API class Billing(API): diff --git a/src/caredaily/apis/admin/devices.py b/src/caredaily/apis/admin/devices.py index 9c172c7..e0a3397 100644 --- a/src/caredaily/apis/admin/devices.py +++ b/src/caredaily/apis/admin/devices.py @@ -5,12 +5,11 @@ # ] # /// -from ..api import API - from ...models import ( APIKeyType, Result, ) +from ..api import API class Devices(API): diff --git a/src/caredaily/apis/admin/firmware.py b/src/caredaily/apis/admin/firmware.py index 5ae4c94..db14655 100644 --- a/src/caredaily/apis/admin/firmware.py +++ b/src/caredaily/apis/admin/firmware.py @@ -5,14 +5,13 @@ # ] # /// -from typing import Dict, Optional - -from ..api import API +from typing import Optional from ...models import ( - Result, APIKeyType, + Result, ) +from ..api import API class Firmware(API): diff --git a/src/caredaily/apis/admin/groups.py b/src/caredaily/apis/admin/groups.py index b839d2c..4f5224c 100644 --- a/src/caredaily/apis/admin/groups.py +++ b/src/caredaily/apis/admin/groups.py @@ -7,12 +7,11 @@ from typing import Dict -from ..api import API - from ...models import ( APIKeyType, Result, ) +from ..api import API class Groups(API): diff --git a/src/caredaily/apis/admin/locations.py b/src/caredaily/apis/admin/locations.py index 0b2dc19..a2d6706 100644 --- a/src/caredaily/apis/admin/locations.py +++ b/src/caredaily/apis/admin/locations.py @@ -7,12 +7,11 @@ from typing import Dict, List -from ..api import API - from ...models import ( APIKeyType, Result, ) +from ..api import API class Locations(API): diff --git a/src/caredaily/apis/admin/narratives.py b/src/caredaily/apis/admin/narratives.py index 6da27a0..f66fe51 100644 --- a/src/caredaily/apis/admin/narratives.py +++ b/src/caredaily/apis/admin/narratives.py @@ -5,12 +5,11 @@ # ] # /// -from ..api import API - from ...models import ( APIKeyType, Result, ) +from ..api import API class Narratives(API): diff --git a/src/caredaily/apis/admin/organizations.py b/src/caredaily/apis/admin/organizations.py index d026a54..39894e0 100644 --- a/src/caredaily/apis/admin/organizations.py +++ b/src/caredaily/apis/admin/organizations.py @@ -7,12 +7,11 @@ from typing import Dict -from ..api import API - from ...models import ( APIKeyType, Result, ) +from ..api import API class Organizations(API): diff --git a/src/caredaily/apis/admin/reports.py b/src/caredaily/apis/admin/reports.py index 0c4ed69..c871d49 100644 --- a/src/caredaily/apis/admin/reports.py +++ b/src/caredaily/apis/admin/reports.py @@ -5,14 +5,13 @@ # ] # /// -from typing import Dict, Optional - -from ..api import API +from typing import Optional from ...models import ( - Result, APIKeyType, + Result, ) +from ..api import API class Reports(API): diff --git a/src/caredaily/apis/admin/tags.py b/src/caredaily/apis/admin/tags.py index 1457fb8..fe1cd44 100644 --- a/src/caredaily/apis/admin/tags.py +++ b/src/caredaily/apis/admin/tags.py @@ -7,12 +7,11 @@ from typing import Dict, List -from ..api import API - from ...models import ( APIKeyType, Result, ) +from ..api import API class Tags(API): diff --git a/src/caredaily/apis/admin/user_groups.py b/src/caredaily/apis/admin/user_groups.py index ed5dfa1..35c7aa6 100644 --- a/src/caredaily/apis/admin/user_groups.py +++ b/src/caredaily/apis/admin/user_groups.py @@ -7,12 +7,11 @@ from typing import Dict -from ..api import API - from ...models import ( - Result, APIKeyType, + Result, ) +from ..api import API class UserGroups(API): diff --git a/src/caredaily/apis/admin/users.py b/src/caredaily/apis/admin/users.py index a0bef5a..2e406b8 100644 --- a/src/caredaily/apis/admin/users.py +++ b/src/caredaily/apis/admin/users.py @@ -5,12 +5,11 @@ # ] # /// -from ..api import API - from ...models import ( - Result, APIKeyType, + Result, ) +from ..api import API class Users(API): diff --git a/src/caredaily/apis/app/__init__.py b/src/caredaily/apis/app/__init__.py index 64c11a9..b153d9e 100644 --- a/src/caredaily/apis/app/__init__.py +++ b/src/caredaily/apis/app/__init__.py @@ -9,8 +9,8 @@ from .clouds_integration import CloudsIntegration from .device_files import DeviceFiles from .device_measurements import DeviceMeasurements -from .devices import Devices from .device_types_and_parameters import DeviceTypesAndParameters +from .devices import Devices from .energy_management import EnergyManagement from .locations import Locations from .paid_services import PaidServices diff --git a/src/caredaily/apis/app/app_files.py b/src/caredaily/apis/app/app_files.py index 7ff3d0e..61c4f6e 100644 --- a/src/caredaily/apis/app/app_files.py +++ b/src/caredaily/apis/app/app_files.py @@ -5,17 +5,9 @@ # ] # /// -import json -from typing import Dict, List, Optional from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API diff --git a/src/caredaily/apis/app/cloud_connectivity.py b/src/caredaily/apis/app/cloud_connectivity.py index c67c2ab..9aadf10 100644 --- a/src/caredaily/apis/app/cloud_connectivity.py +++ b/src/caredaily/apis/app/cloud_connectivity.py @@ -5,17 +5,10 @@ # ] # /// -import json -from typing import Dict, List from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, ServerType, - SignatureAlgorithm, ) from ..api import API diff --git a/src/caredaily/apis/app/clouds_integration.py b/src/caredaily/apis/app/clouds_integration.py index 56acc7c..810ff97 100644 --- a/src/caredaily/apis/app/clouds_integration.py +++ b/src/caredaily/apis/app/clouds_integration.py @@ -5,17 +5,10 @@ # ] # /// -import json -from typing import Dict, List, Optional +from typing import Dict, Optional from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API diff --git a/src/caredaily/apis/app/device_measurements.py b/src/caredaily/apis/app/device_measurements.py index 0671e54..2a69d81 100644 --- a/src/caredaily/apis/app/device_measurements.py +++ b/src/caredaily/apis/app/device_measurements.py @@ -9,16 +9,11 @@ from typing import Dict, List from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API + class DeviceMeasurements(API): """ Device Measurements API for accessing device parameters, readings, and measurement data. diff --git a/src/caredaily/apis/app/devices.py b/src/caredaily/apis/app/devices.py index eee8a2e..18a8b80 100644 --- a/src/caredaily/apis/app/devices.py +++ b/src/caredaily/apis/app/devices.py @@ -9,13 +9,7 @@ from typing import Dict, List, Optional from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API @@ -1093,9 +1087,6 @@ def update_location_device( Reference: https://app.peoplepowerco.com/cloud/apidocs/cloud.html#tag/Devices/operation/Update%20Device """ - params = { - "postId": location_id, # Note: API spec shows postId but should be locationId - } result: Result = self.adapter.put( f"/cloud/json/locations/{location_id}/devices/{device_id}", ep_json=device_data, diff --git a/src/caredaily/apis/app/energy_management.py b/src/caredaily/apis/app/energy_management.py index 4507bf4..04fb9d8 100644 --- a/src/caredaily/apis/app/energy_management.py +++ b/src/caredaily/apis/app/energy_management.py @@ -5,18 +5,11 @@ # ] # /// -import json from datetime import datetime -from typing import Dict, List, Optional +from typing import Dict from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API diff --git a/src/caredaily/apis/app/locations.py b/src/caredaily/apis/app/locations.py index e511dd7..82f9833 100644 --- a/src/caredaily/apis/app/locations.py +++ b/src/caredaily/apis/app/locations.py @@ -10,15 +10,11 @@ from ...models import ( APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API + class Locations(API): """ Locations API for managing user locations and location-related operations. diff --git a/src/caredaily/apis/app/professional_monitoring.py b/src/caredaily/apis/app/professional_monitoring.py index e043e88..130a101 100644 --- a/src/caredaily/apis/app/professional_monitoring.py +++ b/src/caredaily/apis/app/professional_monitoring.py @@ -5,18 +5,11 @@ # ] # /// -import json from datetime import datetime -from typing import Dict, List, Optional +from typing import Dict from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API diff --git a/src/caredaily/apis/app/system_and_user_properties.py b/src/caredaily/apis/app/system_and_user_properties.py index a7a7dd2..2b87dcf 100644 --- a/src/caredaily/apis/app/system_and_user_properties.py +++ b/src/caredaily/apis/app/system_and_user_properties.py @@ -5,17 +5,10 @@ # ] # /// -import json -from typing import Dict, List, Optional +from typing import Dict from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API diff --git a/src/caredaily/apis/app/user_accounts.py b/src/caredaily/apis/app/user_accounts.py index 2a4561a..02012f1 100644 --- a/src/caredaily/apis/app/user_accounts.py +++ b/src/caredaily/apis/app/user_accounts.py @@ -5,20 +5,13 @@ # ] # /// -import json -from typing import Dict, List from ...models import ( - APIKeyType, - Cloud, - MQTT, Result, - Server, - ServerType, - SignatureAlgorithm, ) from ..api import API + class UserAccounts(API): """ User Accounts API for managing user accounts and profiles. diff --git a/src/caredaily/apis/app/user_communication.py b/src/caredaily/apis/app/user_communication.py index b47853d..90d318a 100644 --- a/src/caredaily/apis/app/user_communication.py +++ b/src/caredaily/apis/app/user_communication.py @@ -5,8 +5,7 @@ # ] # /// -import json -from typing import Dict, List, Optional +from typing import Dict, List from ...models import APIKeyType, Result from ..api import API diff --git a/src/caredaily/apis/bot/analytic.py b/src/caredaily/apis/bot/analytic.py index 2a6d64e..c40eb33 100644 --- a/src/caredaily/apis/bot/analytic.py +++ b/src/caredaily/apis/bot/analytic.py @@ -7,11 +7,10 @@ from typing import Dict, List, Optional -from ..api import API - from ...models import ( Result, ) +from ..api import API class Analytic(API): diff --git a/src/caredaily/apis/bot/bot_developer.py b/src/caredaily/apis/bot/bot_developer.py index a960f6f..af81393 100644 --- a/src/caredaily/apis/bot/bot_developer.py +++ b/src/caredaily/apis/bot/bot_developer.py @@ -8,9 +8,9 @@ import json from typing import Dict, List - from ..api import API + # TODO: Finish (see docs/api/bots.yaml) class BotDeveloper(API): """ diff --git a/src/caredaily/apis/bot/bot_store.py b/src/caredaily/apis/bot/bot_store.py index 3bca15f..18ae445 100644 --- a/src/caredaily/apis/bot/bot_store.py +++ b/src/caredaily/apis/bot/bot_store.py @@ -14,6 +14,7 @@ ) from ..api import API + #TODO: Finish (see docs/api/bots.yaml) class BotStore(API): """ diff --git a/src/caredaily/apis/bot/developer_teams.py b/src/caredaily/apis/bot/developer_teams.py index 5b3d46c..d957e3f 100644 --- a/src/caredaily/apis/bot/developer_teams.py +++ b/src/caredaily/apis/bot/developer_teams.py @@ -5,13 +5,7 @@ # ] # /// -import json -from typing import Dict, List -from ...models import ( - APIKeyType, - Runtime, -) from ..api import API diff --git a/src/caredaily/apis/bot/execution.py b/src/caredaily/apis/bot/execution.py index ff1f32c..56b3349 100644 --- a/src/caredaily/apis/bot/execution.py +++ b/src/caredaily/apis/bot/execution.py @@ -4,15 +4,13 @@ # "requests", # ] # /// -import json -from typing import Dict, List from ...models import ( APIKeyType, ) - from ..api import API + class Execution(API): """ Provides methods for listening to device execution analytics and events via the DeviceIO API. diff --git a/src/caredaily/caredaily.py b/src/caredaily/caredaily.py index 8facd57..336e69b 100644 --- a/src/caredaily/caredaily.py +++ b/src/caredaily/caredaily.py @@ -13,6 +13,8 @@ from configparser import ConfigParser from logging import Logger +from dotenv import find_dotenv, load_dotenv + from .apis import ( AdminDevices, AdminLocations, @@ -53,8 +55,6 @@ ) from .exceptions import CareDailyException -from dotenv import load_dotenv, find_dotenv - # Load environment variables from .env file (looks for .env in current or parent directories by default) env_filepath = find_dotenv() load_dotenv() diff --git a/src/caredaily/models.py b/src/caredaily/models.py index fca6614..945555c 100644 --- a/src/caredaily/models.py +++ b/src/caredaily/models.py @@ -7,7 +7,7 @@ from enum import Enum from typing import Dict, List, Optional -from pydantic import BaseModel, Field, ConfigDict +from pydantic import BaseModel, ConfigDict, Field class ResultCode(Enum): diff --git a/tests/caredaily/cli/test_cli_configure.py b/tests/caredaily/cli/test_cli_configure.py index 0e29f1b..6769272 100644 --- a/tests/caredaily/cli/test_cli_configure.py +++ b/tests/caredaily/cli/test_cli_configure.py @@ -1,3 +1,4 @@ +import importlib import os import tempfile import unittest @@ -10,6 +11,11 @@ from caredaily.cli.app import app from caredaily.cli.configure import configure, init, interactive, list, list_profiles +# `caredaily.cli` re-exports the `configure` click group under the same name as +# the module, so the dotted path "caredaily.cli.configure" resolves to the group +# on Python 3.10. Patch the module object directly instead. +configure_module = importlib.import_module("caredaily.cli.configure") + class TestCliConfigure(unittest.TestCase): """Test suite for CLI configure commands""" @@ -60,7 +66,7 @@ def test_configure_help(self): self.assertIn("init", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_init_new_config_without_signin(self, mock_caredaily_class): """Test init command creating new configuration without sign in""" os.environ["HOME"] = self.temp_dir @@ -87,7 +93,7 @@ def test_init_new_config_without_signin(self, mock_caredaily_class): self.assertTrue(os.path.exists(self.credentials_path)) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_init_existing_config(self, mock_caredaily_class): """Test init command with existing configuration""" os.environ["HOME"] = self.temp_dir @@ -188,7 +194,7 @@ def test_init_with_profile_from_env(self, mock_caredaily_class): self.assertIn("testprofile", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_init_availability_check_failure(self, mock_caredaily_class): """Test init command when availability check fails""" os.environ["HOME"] = self.temp_dir @@ -211,7 +217,7 @@ def test_init_availability_check_failure(self, mock_caredaily_class): self.assertIn("Error checking availability", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_list_default_profile(self, mock_caredaily_class): """Test list command with default profile""" os.environ["HOME"] = self.temp_dir @@ -227,7 +233,7 @@ def test_list_default_profile(self, mock_caredaily_class): self.assertIn("key", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_list_specific_profile(self, mock_caredaily_class): """Test list command with specific profile""" os.environ["HOME"] = self.temp_dir @@ -259,7 +265,7 @@ def test_list_specific_profile(self, mock_caredaily_class): self.assertIn("profile.example.com", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_list_nonexistent_profile(self, mock_caredaily_class): """Test list command with non-existent profile""" os.environ["HOME"] = self.temp_dir @@ -272,7 +278,7 @@ def test_list_nonexistent_profile(self, mock_caredaily_class): self.assertIn("not found", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_list_obfuscates_api_key(self, mock_caredaily_class): """Test list command obfuscates API key""" os.environ["HOME"] = self.temp_dir @@ -288,7 +294,7 @@ def test_list_obfuscates_api_key(self, mock_caredaily_class): self.assertNotIn("test_api_key", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_list_profiles(self, mock_caredaily_class): """Test list-profiles command""" os.environ["HOME"] = self.temp_dir @@ -311,7 +317,7 @@ def test_list_profiles(self, mock_caredaily_class): self.assertIn("profile2", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_interactive_without_profile(self, mock_caredaily_class): """Test interactive command without profile specified""" os.environ["HOME"] = self.temp_dir @@ -522,7 +528,7 @@ def test_interactive_with_passcode(self, mock_caredaily_class): self.assertIn("Configured 'test' successfully", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_interactive_not_initialized(self, mock_caredaily_class): """Test interactive command when config is not initialized""" os.environ["HOME"] = self.temp_dir @@ -542,7 +548,7 @@ def test_interactive_not_initialized(self, mock_caredaily_class): self.assertIn("Configuration not initialized", result.output) @patch.dict(os.environ, {"HOME": ""}, clear=True) - @patch("caredaily.cli.configure.CareDaily") + @patch.object(configure_module, "CareDaily") def test_interactive_availability_check_failure(self, mock_caredaily_class): """Test interactive command when availability check fails""" os.environ["HOME"] = self.temp_dir