# Cognitive Systems App Cloud API The AppCloud APIs are used by mobile applications to communicate with the Cognitive Systems Infrastructure. ## Servers ``` /api/v1 ``` ## Security ### Authorization Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Cognitive Systems App Cloud API](https://docs.cognitivesystems.com/_spec/assets/specs/api/app_cloud.yaml) ## Overview ### Build Version - [GET /version](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/overview/get_version.md): Determine App Cloud version and differentiate from Halo Home (legacy) ### Health Probe - [GET /healthz](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/overview/get_healthz.md): Endpoint used by load balancer to determine cloud instance status ## Out of Box ### Store Device Push Token - [POST /mobile_devices](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/post_mobile_devices.md): Store instance token to facilitate the usage of firebase services between App Cloud and Wifi Motion App. The instance token provides a unique identifier for each app instance and a mechanism to authenticate and authorize actions (example: sending FCM messages) If the token sent is set to 'eee-motioncsc-loadtest' the push notification payload will be formed but NOT sent to firebase. This is used in load testing to ensure APPCLD is not blacklisted by Google. ### Delete Members - [DELETE /network_memberships/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/delete_network_memberships-id.md) ### Show Network Members - [GET /network_memberships](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/get_network_memberships.md) ### Create Network Members - [POST /network_memberships](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/post_network_memberships.md) ### Resend Confirmation Email - [POST /confirmation_mails](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/post_confirmation_mails.md): Endpoint to send another confirmation email when user presses 'RESEND EMAIL' button during account creation. ### Confirm New Account - [GET /confirmations](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/get_confirmations.md): After the user receives a confirmation email. This link should open the app, and pass the included token to this User Confirmation GET request. A successful response means that the account associated with the token/email is now confirmed, and can be used for OOB or view network as a member. Note: This is NOT the same token as was returned by the #endpoint:u8SLn5ebDpLA96m7B endpoint. They are both jwt tokens with the same format but they have different token audience, expiry and payload data. ### Send Account Confirmation Email - [POST /confirmations](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/post_confirmations.md): Endpoint to send confirmation email during account creation. ### Create User - [POST /users](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/post_users.md): Creates an unconfirmed user that is not associated with any motion network ### Network Search/Create - [POST /searches](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/post_searches.md): Get or create a Wi-Fi Motion network in App Cloud. The BSSID is shared with Core when the network first comes online. This endpoint verifies the existence of the user's network in Core and if it's claimable. If the network is present in Core, but not in App Cloud, the network is created. Calling this endpoint has one of the following outcomes: - Network not found in MNS Core (404) - Network found, already in App Cloud and returned (200) - Network found, not in App Cloud, created, and returned (200) In the response object, tells you whether the network has an owner. If is false, the network can be claimed by calling /api/v1/network_memberships. If is true, the user can only be added as a member. ### Network Find/Create - [POST /find](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/post_find.md): Get or create a Wi-Fi Motion network in App Cloud. The Guardian Id is shared with Core when the network first comes online. This endpoint verifies the existence of the user's network in Core and if it's claimable. If the network is present in Core, but not in App Cloud, the network is created. Calling this endpoint has one of the following outcomes: - Network not found in MNS Core (404) - Network found, already in App Cloud and returned (200) - Network found, not in App Cloud, created, and returned (200) In the response object, tells you whether the network has an owner. If is false, the network can be claimed by calling /api/v1/network_memberships. If is true, the user can only be added as a member. ### Delete Device Push Token - [DELETE /mobile_devices/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/out-of-box/delete_moble_devices.md): Deletes the firebase token associated with an app. Acts as a log off mechanism to allow a user to deregister a mobile device. ## Logging In ### Login and Begin Session - [POST /sessions](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/post_sessions.md): Session create for a user. Each session create updates a "valid_from" UTC timestamp column in the user model. Any subseqeuent session creates for the same user will invalidate any previously issued tokens, effectively preventing account sharing or multiple devices being logged-in with the same account. ### Re-login and refresh existing session - [PATCH /sessions](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/patch_sessions.md): Used by Wifi Motion app to refresh session and issue new auth + refresh tokens. ### Login using Apple account and Begin Session - [POST /sessions/sso/apple](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/post_sessions_sso_apple.md): This API endpoint allows users to create a session by authenticating via Apple’s Single Sign-On (SSO). The endpoint validates an Apple JWT token and then follows the /sessions flow to establish a user session ### Login using Google account and Begin Session - [POST /sessions/sso/google](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/post_sessions_sso_google.md): This API endpoint allows users to create a session by authenticating via Google’s Single Sign-On (SSO). The endpoint validates an Google JWT token and then follows the /sessions flow to establish a user session ### Login using AWS Cognito and Begin Session - [POST /sessions/sso/cognito](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/post_cognito_sso.md): This API endpoint allows users to create a session by authenticating via AWS Cognito's Single Sign-On (SSO). The endpoint validates an Cognito JWT token and then follows the /sessions flow to establish a user session ### Show Users - [GET /users/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/get_users-id.md): Get basic user information ### Reset Account Password - [PUT /password_resets](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/put_password_resets.md): Update user password. Endpoint used by the 'Enter new password page' in the reset password flow. ### Logout - [POST /logout](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/logging-in/post_logout.md): End the session for the current user. Requires valid JWT. ## Geofencing ### Geofencing Event (iOS) - [POST /bulk_user_presences](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/geofencing/post_bulk_user_presences.md): Endpoint used by Wifi Motion App to report user location and, if enabled, auto update network scene settings. ### Geofencing Event (Android) - [POST /user_presences](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/geofencing/post_user_presences.md): Endpoint used by Wifi Motion App to report user location and, if enabled, auto update network scene settings. Similiar to #endpoint:nm5iMgP7mKxZPTRE5 but only sends one location update instead of multiple. ## Account Management ### Delete Pending Member Invitation - [DELETE /invitations/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/account-management/delete_invitations-id.md) ### Pending Invitations to Network - [GET /invitations](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/account-management/get_invitations.md): Retrieve current list of emails invited to join network ### Update User Model - [PUT /users/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/account-management/put_users-id.md) ### Delete Confirmed User - [DELETE /users/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/account-management/delete_users-id.md) ### Create Pending Invitation - [POST /member_invites](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/account-management/post_member_invites.md): Sends an invite email to the provided list, the link in the email should take the invited users to the app, where they can create an account. NOTE: Only the network owner may send Network Member Invites. ### Set New Account Password - [POST /password_resets](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/account-management/post_password_resets.md): Sends email to given address with password reset link that redirects to static reset page ## Network Settings ### Update Node Settings - [PUT /node](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/put_node.md) ### Show General Settings (With ID) - [GET /networks/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/get_networks-id.md): - The field in the res json defaults to an int which represents the row_id of the scene config in postgres. - To retrieve the full scene config for the network, use the param with a single array item of ### Update General Settings - [PUT /networks/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/put_networks-id.md): - Updates App Cloud network with user-specific information. User must have the role "owner" for the corresponding network. - Request body does not require all listed fields, but fields must match type and value validations - To update the timezone, only pass in the request body: ### Disown Network - [DELETE /networks/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/delete_networks-id.md): - Disowns a given network, user must be owner. - Removes rows from following tables in postgres - networks - network memberships - network scene configs - invitations - mobile devices - users - Also propogates delete to MNS ### Show Scene Settings - [GET /network_scene_configs/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/get_network_scene_configs-id.md) ### Update Scene Settings - [PUT /network_scene_configs/{id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/put_network_scene_configs-id.md) ### Show Motion Settings - [GET /network_motion_config](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/get_network_motion_config.md) ### Update Motion Settings - [PUT /network_motion_config](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/put_network_motion_config.md) ### Show Default Locations - [GET /default_locations](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/get_default_locations.md) ### Create Default Location - [POST /default_locations](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/post_default_locations.md) ### Show All Scenes - [GET /scenes](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/get_scenes.md) ### Update scene event for user's network - [PUT /scenes](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/put_scenes.md): Change the scene of user's network. Accepts : - 1 : SceneChangedToAwayEvent - 4 : SceneChangedToHomeEvent ### Show General Settings - [GET /networks](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/get_networks.md): Android and iOS versions app have variations in how the request + response for GET /networks is made. There is a top level data key that is sometimes expected and other times is not, and there is differences in the id parameter. ### Update Leaf Settings - [PUT /leaf](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/put_leaf.md) ### Show Network Info - [GET /networks/info](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/network-settings/get_networks_info.md): Returns the following internal network identifiers: - guardian_id - external_id - network_id - nodes ## Sounding v2 ### Get Global Settings - [GET /sounding/settings](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/sounding-v2/get_sounding-settings.md): This endpoint allows retreival of key global configuration options for leaf/node (where applicable) sounding behaviour. ### Update Global Settings - [PATCH /sounding/settings](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/sounding-v2/patch_sounding-settings.md): This endpoint allows the manipulation of key global configuration options for leaf/node (where applicable) sounding behaviour. ### Get Client State - [GET /sounding/clients](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/sounding-v2/get_sounding-clients.md): This endpoint allows client-level sounding control and feedback. ### Set Client Config - [PATCH /sounding/clients](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/sounding-v2/patch_sounding-clients.md): This endpoint allows client-level sounding control and feedback. ## Events, History, and Visualizations ### Tag Motion Detected Event - [POST /event_tag](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/post_event_tag.md) ### Motion History Densities - [GET /motion_history_densities](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/get_motion_history_densities.md): Returns historical motion densities for a given period of time. Densities are percentages representing how many samples within a bucket-size had motion values greater than zero. For example, if the bucket size was 60 seconds, and 11 of the 12 possible 5s buckets had motion then a value of 91.6 would be returned. It should be noted that data is stored in two resolutions: 1s intervals for the last 24 hours. 5s intervals for the last week. Which means that densities computed on data within the last 24 hours may be retrieved with this request at sub 5s bucket sizes. This request may return data at a coarser resolution than the requested bucket size, if data at that resolution is not available. Timestamp ranges are limited by Halo Home to only include times over which the network was last claimed. ### Last Motion Detected Timestamp - [GET /network_statuses](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/get_network_statuses.md) ### Motion Detected Detail View - [GET /location_histograms](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/get_location_histograms.md) ### Network Topology - [GET /topologies](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/get_topologies.md): Provides the topology of the network. ### Hourly Motion Histograms - [GET /motion_history_intensities](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/get_motion_history_intensities.md): Returns historical motion intensities for a given period of time. Intensities are actual motion values stored at two different resolutions (bucket sizes): - 1s intervals for the last 24 hours. - 5s intervals for the last week. This request may return data at a coarser resolution than the requested bucket size, if data at that resolution is not available. Timestamp ranges are limited by Halo Home to only include times over which the network was last claimed. ### Live Motion Websocket - [GET /motions](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/get_motions.md): Open a Websocket connection streaming live motion data. ### Network Event History - [GET /events](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/events-history-and-visualizations/get_events.md) ## Household Insights [BETA] ### Get Sleep-Wake Settings - [GET /sleep_times/settings](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/household-insights-beta/get_sleep_times-settings.md): Both the owner or the member bound to the network can consume this endpoint. Responds to the application whether sleep feature is enabled, and the user-provided household sleep time and household wake time. If the owner has not yet enabled the feature via, the following template is sent: A record of the household settings is made only when the feature is enabled for the first time. ### Set Sleep-Wake Settings - [POST /sleep_times/settings](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/household-insights-beta/post_sleep_times-settings.md): Only the user with a role of "owner" can make a request to this endpoint. ### Household Sleep-Wake Times Data - [GET /sleep_times/data/{queried_days}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/household-insights-beta/get_sleep_times-data-queried_days.md): This endpoint retrieves the timezone of the user from the network model and supplies it to the micro service. The micro service will return hour values for wake and sleep in the network's timezone. ### [BETA] Retrieve Activity Insights - [GET /insights/v2/activity](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/household-insights-beta/get_activity_insights_v2__network_id__activity_get.md): [BETA] Activity Insights provides you activity related data. ### Household Activity - [GET /activity/{queried_days}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/household-insights-beta/get_activity-queried_days.md): Available in App Cloud v1-3-22 and above. Requires the Home-Insights Microservice enabled within MNS. ## Zone Priority [BETA] ### Show current zone priority list - [GET /zone_priority](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/zone-priority-beta/get_zone_priority.md) ### Replace zone priority list - [PATCH /zone_priority](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/zone-priority-beta/patch_zone_priority.md): Accepts a list or array of strings, these do not have to match or be contained in the list of strings produced by . Patching is not additive, every request will replace the values. Making this list empty is the feature switch on whether to use the new zone prioritized leaf blower, or whether to default to legacy leaf blower. tells the network to use legacy leaf blower. Non empty, for example: disables legacy leaf blower and enables the zone prioritized leaf blower. ### Batch update leafs and nodes - [PATCH /devices](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/zone-priority-beta/patch_devices.md): Receives a list of objects that mutate nodes and/or leafs. Network nodes (star or mesh) cannot be targeted using a but only using the . The key is also not supported by nodes so the input validation will throw. Mutations to node require and cannot include or . We expect leafs in the array to not have , and they must have and . Both mutations to nodes or leafs must always have and keys. Order does not matter. The payload can include only leafs or only nodes. ## Universal Alerting ### Retrieve Universal Alert rules - [GET /universal-alert](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/universal-alerting/get_universal_alert.md): Returns an array of all universal alert rules associated with the network. ### Create a single custom rule - [POST /universal-alert](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/universal-alerting/post_universal_alert.md): Creates a single custom Wifi Motion Alert. ### Get Universal Alert Status - [GET /universal-alert/status](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/universal-alerting/get_universal_alert_status.md): Returns an array of all alerts associated with the network, but from the view of the job queue, including all the internal state of the job. The data field of this response contains the client facing alert alert model. This endpoint is to assist with seeing the internals of the job queue. ### Get universal alert - [GET /universal-alert/{uuid}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/universal-alerting/get_universal_alert_.md): Get a single alert by its uuid. ### Delete Universal Alert - [DELETE /universal-alert/{uuid}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/universal-alerting/delete_universal_alert.md): Deletes an alert by its uuid. A successful delete will return the entire alert model. Only the alerts owned by the network can be deleted. And these alerts can be deleted by both member or owner. ### Update of Single Alert - [PATCH /universal-alert/{uuid}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/universal-alerting/patch_universal-alert.md): Update a single alert If an alert has been switched into an state because the alert has completed every possible recurrence, the mutation must include a new RRULE that has at least one occurrence in the future. Under the hood, PATCH is a get job, delete job, and create a job. Note that the following parameters cannot be mutated via the PATCH: - external_id - uuid - options path parameter can only be the uuid ### Universal Alert Bulk Enable - [PATCH /universal-alert-bulk](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/universal-alerting/patch_universal_alert_bulk.md): Enable or disable multiple alerts. ## Meta ### Get Meta of Network - [GET /meta](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/meta/get_meta.md): Shows the network's meta storage ### Patch Meta Storage - [PATCH /meta](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/meta/patch_meta.md): The API supports two storage areas: - network: a storage area that is shared by all network users, writable by the owner but only readable by a member - user: a read/write storage area that is only visible to the current user (member or owner) ### Delete Meta Storage - [DELETE /meta](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/meta/delete_meta.md): Deletes network meta storage. Only the owner can perform this action. ### [BETA] Get Meta of User - [GET /user/meta](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/meta/get_user_meta.md): Shows the user's meta storage ### [BETA] Patch Meta User Storage - [PATCH /user/meta](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/meta/patch_user_meta.md): Appends or overwrites the user meta storage. ### [BETA] Delete Meta User Storage - [DELETE /user/meta](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/meta/delete_user_meta.md): Deletes user meta storage. ## Administration ### Display network and related config - [GET /internal/network/{network_id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/get_internal-network-network_id.md): Retrieve all network related data from postgres and MNS for a single network. This includes network, members, scenes, login, and events information. ### List Network Owners - [GET /internal/users/{page_number}/{count_number}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/get_internal-users-page_number-count_number.md): Retrieve paginated array of all users that are network owners ### Password Reset - [PATCH /internal/users/reset](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/patch_internal-users-reset.md) ### Global Search - [GET /internal/search/{search_key}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/get_internal-search-search_key.md) ### Search Users - [GET /internal/users/search/{name}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/get_internal-users-search-name.md): Retrieves array of all users that have similar firstname or lastname. ### All Cached Networks - [GET /internal/network_map](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/get_internal-network_map.md): This endpoint returns all network model stored in the app-cloud. Network models are stored in cache which can be made on-demand by setting ensure field to true. Default radius is 5km, if latitude and longitude is supplied with the request. Haversine Distance is used as distance metric to find networks. ### Paginate Networks - [GET /internal/networks/{page_number}/{count_number}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/get_internal-networks-page_number-count_number.md): Retrieve paginated array of ALL networks in cloud. ### Invite new user - [POST /internal/invite](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/post_internal-invite.md): Sends network invitation email to specified email for the given network. ### Reset Out of Boxing - [PATCH /internal/oob/{network_id}](https://docs.cognitivesystems.com/assets/specs/api/app_cloud/administration/patch-internal-oob-network-id.md): Reset out of boxing by removing members from network. Resets network's latitude, longitude and address and updates timezone to Eastern Time.