{ "components": { "securitySchemes": { "BearerJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Error": { "type": "object", "properties": { "code": { "type": "integer", "description": "Error code" }, "status": { "type": "string", "description": "Error name" }, "message": { "type": "string", "description": "Error message" }, "errors": { "type": "object", "description": "Errors", "additionalProperties": {} } }, "additionalProperties": false }, "PaginationMetadata": { "type": "object", "properties": { "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "first_page": { "type": "integer" }, "last_page": { "type": "integer" }, "page": { "type": "integer" }, "previous_page": { "type": "integer" }, "next_page": { "type": "integer" } }, "additionalProperties": false }, "AssistantResponse": { "type": "object", "properties": { "assistantType": { "enum": [ "alexa", "google", "homey" ] }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "region": { "type": "string", "nullable": true }, "objectIds": { "type": "string", "nullable": true }, "homeyDeviceIds": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AssistantModify": { "type": "object", "properties": { "assistantType": { "readOnly": true, "enum": [ "alexa", "google", "homey" ] }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "region": { "type": "string", "readOnly": true }, "objectIds": { "type": "string", "readOnly": true, "nullable": true }, "homeyDeviceIds": { "type": "string", "nullable": true } }, "required": [ "accessToken", "refreshToken" ], "additionalProperties": false }, "Assistant": { "type": "object", "properties": { "assistantType": { "enum": [ "alexa", "google", "homey" ] }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" }, "region": { "type": "string", "nullable": true }, "objectIds": { "type": "string", "nullable": true }, "homeyDeviceIds": { "type": "string", "nullable": true } }, "additionalProperties": false }, "AssistantLink": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "The access token to be used in the API calls" }, "refreshToken": { "type": "string", "description": "The token to be used when asking to refresh an existing token" }, "region": { "type": "string", "default": null, "description": "The region the token is valid for, if any", "nullable": true }, "serviceUserId": { "type": "string", "description": "The optional service user ID to be associated with our user ID" }, "homeyDeviceId": { "type": "string", "description": "The optional Homey device ID to be associated with our user ID" } }, "required": [ "accessToken", "refreshToken" ], "additionalProperties": false }, "AssistantLink1": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "The access token to be used in the API calls" }, "refreshToken": { "type": "string", "description": "The token to be used when asking to refresh an existing token" }, "region": { "type": "string", "default": null, "description": "The region the token is valid for, if any", "nullable": true }, "serviceUserId": { "type": "string", "description": "The optional service user ID to be associated with our user ID" }, "homeyDeviceId": { "type": "string", "description": "The optional Homey device ID to be associated with our user ID" } }, "additionalProperties": false }, "AssistantUnlink": { "type": "object", "properties": { "objectId": { "type": "string", "description": "The ID of the object being disconnected from the assistant" }, "serviceUserId": { "type": "string", "description": "The service ID of the user to be unlinked (Alexa only)" } }, "additionalProperties": false }, "AssistantObjects": { "type": "object", "properties": { "objectIds": { "type": "array", "items": { "type": "integer" } } }, "required": [ "objectIds" ], "additionalProperties": false }, "ObjectCapability": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "name": { "type": "string", "description": "The name of the capability" }, "properties": { "type": "object", "description": "The properties of the capability", "additionalProperties": {} } }, "additionalProperties": false }, "ObjectInstallationDetails": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the installation" }, "name": { "type": "string", "description": "The name the user gave to this installation", "nullable": true } }, "additionalProperties": false }, "Object": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "id": { "type": "integer", "description": "The unique ID of this object" }, "name": { "type": "string", "description": "The name of this object" }, "ledCount": { "type": "integer", "description": "The total number of leds of this object" }, "ledProfile": { "type": "string", "description": "The led profile of this object" }, "fps": { "type": "number", "description": "The Frame Per Second configured for this object" }, "capacity": { "type": "integer", "description": "The maximum capacity of this object" }, "opMode": { "type": "integer", "description": "The operation mode of this object" }, "ownerId": { "type": "integer", "description": "The unique ID of the owner of this object" }, "family": { "type": "string", "description": "The family of the object, derived from the devices associated with the object" }, "uuid": { "type": "string", "description": "A unique ID that identify this object" }, "caps": { "type": "array", "description": "The list of capabilities supported by the object", "items": { "$ref": "#/components/schemas/ObjectCapability" } }, "meta": { "type": "string", "description": "The metadata associates with this object" }, "installation": { "description": "The installation details this object is part of", "allOf": [ { "$ref": "#/components/schemas/ObjectInstallationDetails" } ] } }, "additionalProperties": false }, "AssistantDiscovery": { "type": "object", "properties": { "objects": { "type": "array", "description": "The list of objects", "items": { "$ref": "#/components/schemas/Object" } } }, "additionalProperties": false }, "BaseLogoutRequest": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "refresh_token": { "type": "string", "description": "Refresh token obtained from last call to token request or refresh" } }, "required": [ "refresh_token" ], "additionalProperties": false }, "Services": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "authenticationProvider": { "type": "boolean", "readOnly": true, "description": "Status of authentication provider" }, "db": { "type": "boolean", "readOnly": true, "description": "Status of database provider" } }, "additionalProperties": false }, "Status": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "deep": { "type": "boolean", "default": false, "writeOnly": true, "description": "The type of status check to perform: if true, the auxiliary services status will be returned, otherwise return an OK response" }, "services": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/Services" } ] }, "system": { "readOnly": true, "description": "Return the overall status of the system, based on authentication provider and database status" }, "version": { "type": "string", "readOnly": true, "description": "The Git SHA version of the running system" } }, "additionalProperties": false }, "Document": { "type": "object", "properties": { "id": { "type": "integer", "description": "Document id" }, "type": { "type": "string", "description": "Document type" }, "version": { "type": "integer", "description": "Version of the document" }, "contentUrl": { "type": "string", "description": "Content utl to the document" }, "created": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date that the resource has been created" } }, "additionalProperties": false }, "CreateDocumentRequest": { "type": "object", "properties": { "type": { "type": "string", "description": "Document type" }, "contentUrl": { "type": "string", "description": "Content utl to the document" } }, "required": [ "contentUrl", "type" ], "additionalProperties": false }, "HomeKitAccessory": { "type": "object", "properties": { "pp": { "type": "string", "writeOnly": true }, "sku": { "type": "string", "writeOnly": true }, "macAddress": { "type": "string", "writeOnly": true }, "uuid": { "type": "string", "writeOnly": true } }, "required": [ "macAddress", "pp", "sku", "uuid" ], "additionalProperties": true }, "HomeKitBase": { "type": "object", "properties": { "pp": { "type": "string", "writeOnly": true } }, "required": [ "pp" ], "additionalProperties": true }, "MonitorTargetResponse": { "type": "object", "properties": { "created": { "type": "string", "format": null, "writeOnly": true, "pattern": null }, "updated": { "type": "string", "format": null, "writeOnly": true, "pattern": null }, "id": { "type": "integer", "description": "ID of the target being monitored" }, "type": { "type": "string", "description": "Type of the target (e.g., device, service)" } }, "required": [ "id", "type" ], "additionalProperties": false }, "MonitorEvent": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "type": { "type": "string", "enum": [ "runtime.status.changed", "runtime.mode.changed" ], "description": "Type of the event being monitored" }, "debounceSeconds": { "type": "integer", "description": "Debounce time in seconds for the event" } }, "required": [ "type" ], "additionalProperties": false }, "NotificationTimeWindowCompiled": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "dayMask": { "type": "integer", "description": "Bitmask representing the days of the week" }, "startMinute": { "type": "integer", "description": "Start time in minutes since midnight" }, "endMinute": { "type": "integer", "description": "End time in minutes since midnight" }, "spansMidnight": { "type": "boolean", "description": "Indicates if the time window spans midnight" } }, "additionalProperties": false }, "NotificationTimeWindow": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "days": { "type": "array", "description": "Days of the week when notifications are sent", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } }, "startTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$", "description": "Start time of the notification window (HH:MM format)" }, "endTime": { "type": "string", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$", "description": "End time of the notification window (HH:MM format)" }, "_compiled": { "readOnly": true, "allOf": [ { "$ref": "#/components/schemas/NotificationTimeWindowCompiled" } ] } }, "required": [ "days", "endTime", "startTime" ], "additionalProperties": false }, "NotificationEnabled": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "value": { "type": "boolean", "description": "Indicates if notifications are enabled" }, "timeWindows": { "type": "array", "description": "Time windows during which notifications are enabled", "items": { "$ref": "#/components/schemas/NotificationTimeWindow" } } }, "required": [ "value" ], "additionalProperties": false }, "NotificationChannel": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "type": { "type": "string", "enum": [ "slack", "telegram", "email" ], "description": "Type of the notification channel" }, "attributes": { "type": "object", "description": "Attributes specific to the notification channel type", "additionalProperties": {} }, "timeWindows": { "type": "array", "description": "Time windows for the notification channel", "items": { "$ref": "#/components/schemas/NotificationTimeWindow" } } }, "required": [ "attributes", "type" ], "additionalProperties": false }, "MonitorNotification": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "enabled": { "description": "Whether notifications are enabled for the monitor", "allOf": [ { "$ref": "#/components/schemas/NotificationEnabled" } ] }, "message": { "type": "string", "maxLength": 1024, "description": "Optional notification message", "nullable": true }, "channels": { "type": "array", "minItems": 1, "description": "List of notification channels (e.g., email, SMS)", "items": { "$ref": "#/components/schemas/NotificationChannel" } } }, "required": [ "channels", "enabled" ], "additionalProperties": false }, "MonitorResponse": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "id": { "type": "string", "description": "Unique monitor identifier" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Monitor name" }, "description": { "type": "string", "maxLength": 1024, "description": "Optional monitor description", "nullable": true }, "targets": { "type": "array", "description": "List of monitor targets", "items": { "$ref": "#/components/schemas/MonitorTargetResponse" } }, "events": { "type": "array", "minItems": 1, "description": "List of events associated with the monitor", "items": { "$ref": "#/components/schemas/MonitorEvent" } }, "notification": { "description": "Notification settings for the monitor", "allOf": [ { "$ref": "#/components/schemas/MonitorNotification" } ] } }, "required": [ "events", "id", "name", "notification", "targets" ], "additionalProperties": false }, "GetMonitorsResponse": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "monitors": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorResponse" } }, "count": { "type": "integer", "description": "Total number of results for this query" }, "next_page": { "type": "integer", "description": "The next page that can be retrieved for monitors pagination: it is None if no more pages are available" }, "prev_page": { "type": "integer", "description": "The previous page that can be retrieved for monitors pagination: it is None if no more previous pages are available" } }, "additionalProperties": false }, "MonitorTarget": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "id": { "type": "integer", "description": "ID of the target being monitored" }, "type": { "type": "string", "description": "Type of the target (e.g., device, service)" } }, "required": [ "id", "type" ], "additionalProperties": false }, "CreateMonitorsRequest": { "type": "object", "properties": { "created": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date that the resource has been created" }, "updated": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date that the resource has been updated" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Monitor name" }, "description": { "type": "string", "maxLength": 1024, "description": "Optional monitor description", "nullable": true }, "targets": { "type": "array", "minItems": 1, "description": "List of monitor targets", "items": { "$ref": "#/components/schemas/MonitorTarget" } }, "events": { "type": "array", "minItems": 1, "description": "List of events associated with the monitor", "items": { "$ref": "#/components/schemas/MonitorEvent" } }, "notification": { "description": "Notification settings for the monitor", "allOf": [ { "$ref": "#/components/schemas/MonitorNotification" } ] } }, "required": [ "events", "name", "notification", "targets" ], "additionalProperties": false }, "UpdateMonitorRequest": { "type": "object", "properties": { "created": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date that the resource has been created" }, "updated": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date that the resource has been updated" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Monitor name" }, "description": { "type": "string", "maxLength": 1024, "description": "Optional monitor description", "nullable": true }, "targets": { "type": "array", "minItems": 1, "description": "List of monitor targets", "items": { "$ref": "#/components/schemas/MonitorTarget" } }, "events": { "type": "array", "minItems": 1, "description": "List of events associated with the monitor", "items": { "$ref": "#/components/schemas/MonitorEvent" } }, "notification": { "description": "Notification settings for the monitor", "allOf": [ { "$ref": "#/components/schemas/MonitorNotification" } ] } }, "additionalProperties": false }, "WebhookEvent": { "type": "object", "properties": { "eventType": { "type": "string", "description": "The type of event" }, "eventMeta": { "type": "object", "description": "Custom metadata associated with event type", "additionalProperties": {}, "nullable": true } }, "required": [ "eventType" ], "additionalProperties": false }, "WebhookResponse": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "id": { "type": "integer", "readOnly": true, "description": "Unique identifier of the webhook created" }, "url": { "type": "string", "format": "url", "description": "URL to be called" }, "name": { "type": "string", "description": "Optional name of the webhook", "nullable": true }, "headers": { "type": "object", "description": "A dictionary of key-value pairs to specify additional headers to be added when calling the webhook", "additionalProperties": { "type": "string" }, "nullable": true }, "authType": { "type": "string", "default": null, "description": "The type of authentication to be used", "nullable": true }, "authData": { "type": "string", "default": "", "description": "The value required for the authentication type", "nullable": true }, "events": { "description": "The list of events that will trigger this webhook", "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "status": { "type": "string", "readOnly": true, "description": "The status of this webhook" }, "userId": { "type": "integer", "readOnly": true, "description": "The unique ID of the user associated to this webhook" } }, "required": [ "events", "url" ], "additionalProperties": false }, "WebhooksResponse": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResponse" } }, "next_page": { "type": "integer", "description": "The next page that can be retrieved for webhooks pagination: it is None if no more pages are available" }, "prev_page": { "type": "integer", "description": "The previous page that can be retrieved for webhooks pagination: it is None if no more previous pages are available" } }, "additionalProperties": false }, "WebhookRequest": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "id": { "type": "integer", "readOnly": true, "description": "Unique identifier of the webhook created" }, "url": { "type": "string", "format": "url", "description": "URL to be called" }, "name": { "type": "string", "description": "Optional name of the webhook", "nullable": true }, "headers": { "type": "object", "description": "A dictionary of key-value pairs to specify additional headers to be added when calling the webhook", "additionalProperties": { "type": "string" }, "nullable": true }, "authType": { "type": "string", "default": null, "description": "The type of authentication to be used", "nullable": true }, "authData": { "type": "string", "default": "", "description": "The value required for the authentication type", "nullable": true }, "events": { "description": "The list of events that will trigger this webhook", "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "status": { "type": "string", "readOnly": true, "description": "The status of this webhook" }, "userId": { "type": "integer", "readOnly": true, "description": "The unique ID of the user associated to this webhook" } }, "required": [ "events", "url" ], "additionalProperties": false }, "WebhookRequest1": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "id": { "type": "integer", "readOnly": true, "description": "Unique identifier of the webhook created" }, "url": { "type": "string", "format": "url", "description": "URL to be called" }, "name": { "type": "string", "description": "Optional name of the webhook", "nullable": true }, "headers": { "type": "object", "description": "A dictionary of key-value pairs to specify additional headers to be added when calling the webhook", "additionalProperties": { "type": "string" }, "nullable": true }, "authType": { "type": "string", "default": null, "description": "The type of authentication to be used", "nullable": true }, "authData": { "type": "string", "default": "", "description": "The value required for the authentication type", "nullable": true }, "events": { "description": "The list of events that will trigger this webhook", "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "status": { "type": "string", "readOnly": true, "description": "The status of this webhook" }, "userId": { "type": "integer", "readOnly": true, "description": "The unique ID of the user associated to this webhook" } }, "additionalProperties": false }, "WebhookStatusRequest": { "type": "object", "properties": { "created": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been created", "pattern": null }, "updated": { "type": "string", "format": null, "readOnly": true, "description": "The date that the resource has been updated", "pattern": null }, "status": { "type": "string", "description": "The status of the webhook" } }, "required": [ "status" ], "additionalProperties": false } }, "responses": { "UNPROCESSABLE_ENTITY": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "DEFAULT_ERROR": { "description": "Default error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NOT_MODIFIED": { "description": "Not Modified" } }, "parameters": { "IF_NONE_MATCH": { "name": "If-None-Match", "in": "header", "description": "Tag to check against", "schema": { "type": "string" } } }, "headers": { "ETAG": { "description": "Tag for the returned entry", "schema": { "type": "string" } } } }, "security": [ { "BearerJWT": [] } ], "paths": { "/private/assistants": { "get": { "parameters": [ { "in": "query", "name": "userIds", "description": "A comma-separated list of user ids", "schema": { "type": "string" }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Retrieve the assistants associated with a list of user IDs", "description": "This endpoint can be called only from system services", "tags": [ "assistantsPrivate" ] } }, "/private/assistants/{user_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Retrieve the assistants associated with a user ID", "description": "This endpoint can be called only from system services", "tags": [ "assistantsPrivate" ] }, "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer", "minimum": 0 } } ] }, "/private/assistants/{user_id}/{assistant_type}": { "put": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assistant" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantModify" } } } }, "summary": "Updated the assistant type specified associated with a user ID", "description": "This endpoint can be called only from system services", "tags": [ "assistantsPrivate" ] }, "delete": { "responses": { "204": { "description": "No Content" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Updated the assistants associated with a user ID", "description": "This endpoint can be called only from system services", "tags": [ "assistantsPrivate" ] }, "parameters": [ { "in": "path", "name": "user_id", "required": true, "schema": { "type": "integer", "minimum": 0 } }, { "in": "path", "name": "assistant_type", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v2/assistants": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Retrieve the assistants associated with caller", "tags": [ "assistants" ] } }, "/v2/assistants/{assistant_type}/link": { "post": { "parameters": [ { "in": "path", "name": "assistant_type", "description": "The type of assistant", "schema": { "type": "string", "enum": [ "alexa", "google", "homey" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantLink" } } } }, "summary": "Store tokens to access assistant gateways", "description": "Because the way the skill is built, we can not receive the event of Skill disconnection, so if\nwe try to add a new token for a user already associated with an assistant, we simply update\nthe existent data, because this call is done when a user enable the skill.", "tags": [ "assistants" ] }, "put": { "parameters": [ { "in": "path", "name": "assistant_type", "description": "The type of assistant", "schema": { "type": "string", "enum": [ "alexa", "google", "homey" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantLink1" } } } }, "summary": "Update tokens to access assistant gateways", "tags": [ "assistants" ] }, "delete": { "parameters": [ { "in": "path", "name": "assistant_type", "description": "The type of assistant", "schema": { "type": "string", "enum": [ "alexa", "google", "homey" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "204": { "description": "No Content" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantUnlink" } } } }, "summary": "Remove the association between an user and an assistant", "tags": [ "assistants" ] }, "parameters": [ { "in": "path", "name": "assistant_type", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v2/assistants/{assistant_type}/objects": { "put": { "parameters": [ { "in": "path", "name": "assistant_type", "description": "The type of assistant", "schema": { "type": "string", "enum": [ "alexa", "google", "homey" ] }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantObjects" } } } }, "summary": "Store the list of objects owned by the user to be returned to the assistants", "tags": [ "assistants" ] }, "parameters": [ { "in": "path", "name": "assistant_type", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v2/assistants/discovery": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistantDiscovery" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Get the list of objects owned by the user to be returned to the assistants", "description": "This is a simplified version of the classic GET /objects\nThe following assumptions are done:\n - all objects owned by the user are returned (type=0)\n - the capabilities field is returned\n - before return, the object ids are checked against legacyObjectMapper: if any match is found, the id will be changed to the mapped one", "tags": [ "assistants" ] } }, "/v2/products": { "get": { "responses": { "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Retrieve products list directly from S3 (or from cache, if present)", "tags": [ "base" ] } }, "/v2/lamps": { "get": { "responses": { "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Retrieve products list directly from S3 (or from cache, if present)", "tags": [ "base" ] } }, "/v2/logout": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseLogoutRequest" } } } }, "summary": "Request to logout a user through invalidation of refresh token", "description": "After this call, a user to be authenticated will need to request a new token\nusing the /auth endpoint, because refresh token could not be used to request a\nnew token.\nNOTE: invalidate user cache if any, and disable expiry verification in decode,\nbecause offline refresh token does not have an expiry", "tags": [ "base" ] } }, "/v2/status": { "get": { "parameters": [ { "in": "query", "name": "deep", "description": "The type of status check to perform: if true, the auxiliary services status will be returned, otherwise return an OK response", "schema": { "type": "boolean", "default": false, "writeOnly": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Check overall system status", "description": "A querystring parameter 'deep' will select if a full check will\nbe done or only a partial check", "tags": [ "base" ] } }, "/v2/documents": { "get": { "parameters": [ { "in": "query", "name": "type", "description": "Comma separated list of document type", "schema": { "type": "string" }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Get document list", "tags": [ "documents" ] }, "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequest" } } } }, "summary": "Create document new version", "tags": [ "documents" ] } }, "/v2/documents/latest": { "get": { "parameters": [ { "in": "query", "name": "type", "description": "Comma separated list of document type", "schema": { "type": "string" }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Get document list based on type", "tags": [ "documents" ] } }, "/v2/documents/{type}": { "get": { "parameters": [ { "in": "query", "name": "version", "description": "Version of the document", "schema": { "type": "integer" }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "302": { "description": "Found" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Redirect to requested document", "tags": [ "documents" ] }, "parameters": [ { "name": "type", "in": "path", "description": "Type of document to retrieve", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v2/hk/accessory": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HomeKitAccessory" } } } }, "summary": "Call the backend service that handle homekit interaction", "description": "UUID specified must be present in the database for device", "tags": [ "hk" ] } }, "/v2/hk/accessory/{uuid}": { "get": { "parameters": [ { "in": "query", "name": "pp", "schema": { "type": "string", "writeOnly": true }, "required": true } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Call the backend service that handle homekit interaction", "tags": [ "hk" ] }, "parameters": [ { "in": "path", "name": "uuid", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v2/hk/productionBatch": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HomeKitBase" } } } }, "summary": "Call the backend service that handle homekit interaction", "description": "UUID specified must be present in the database for device", "tags": [ "hk" ] } }, "/v2/hk/productionLog": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HomeKitBase" } } } }, "summary": "Call the backend service that handle homekit interaction", "description": "UUID specified must be present in the database for device", "tags": [ "hk" ] } }, "/v2/hk/authEntityRequest": { "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HomeKitBase" } } } }, "summary": "Call the backend service that handle homekit interaction", "description": "UUID specified must be present in the database for device", "tags": [ "hk" ] } }, "/v2/monitors": { "get": { "parameters": [ { "in": "query", "name": "page", "description": "The page number of users to be retrieved (for pagination)", "schema": { "type": "integer", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "limit", "description": "Number of results per page to return", "schema": { "type": "integer", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "name", "description": "Filter monitors by name", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "targetType", "description": "Filter monitors by target type", "schema": { "type": "string" }, "required": false }, { "in": "query", "name": "targetIds", "description": "Comma-separated string representing the IDs of targets.", "schema": { "type": "string" }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMonitorsResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Get monitor list with filters", "tags": [ "monitors" ] }, "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorsRequest" } } } }, "summary": "Create a new monitor", "tags": [ "monitors" ] } }, "/v2/monitors/{monitor_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Get monitor details by ID", "tags": [ "monitors" ] }, "put": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitorRequest" } } } }, "summary": "Update monitor by ID with partial updates and Redis sync", "tags": [ "monitors" ] }, "delete": { "responses": { "204": { "description": "No Content" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Delete monitor by ID", "tags": [ "monitors" ] }, "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor unique identifier", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/version": { "get": { "responses": { "200": { "description": "OK" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "tags": [ "rootPrivate" ] } }, "/.well-known/apple-app-site-association": { "get": { "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETAG" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "304": { "$ref": "#/components/responses/NOT_MODIFIED" } }, "parameters": [ { "$ref": "#/components/parameters/IF_NONE_MATCH" } ], "summary": "Authorize Apple App association with universal link", "tags": [ "root" ] } }, "/apple-app-site-association": { "get": { "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETAG" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "304": { "$ref": "#/components/responses/NOT_MODIFIED" } }, "parameters": [ { "$ref": "#/components/parameters/IF_NONE_MATCH" } ], "summary": "Authorize Apple App association with universal link", "tags": [ "root" ] } }, "/.well-known/assetlinks.json": { "get": { "responses": { "200": { "description": "OK", "headers": { "ETag": { "$ref": "#/components/headers/ETAG" } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" }, "304": { "$ref": "#/components/responses/NOT_MODIFIED" } }, "parameters": [ { "$ref": "#/components/parameters/IF_NONE_MATCH" } ], "summary": "Authorize Android App association with universal link", "tags": [ "root" ] } }, "/v2/stats": { "get": { "responses": { "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "tags": [ "stats" ] } }, "/v2/stats/{stat_id}": { "get": { "parameters": [ { "in": "query", "name": "output", "schema": { "type": "string", "default": "html" }, "required": false }, { "in": "query", "name": "debug", "schema": { "type": "boolean", "default": false }, "required": false }, { "in": "query", "name": "from", "schema": { "type": "string", "format": null, "default": "1970-01-01", "pattern": null }, "required": false }, { "in": "query", "name": "to", "schema": { "type": "string", "format": null, "default": null, "pattern": null, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "tags": [ "stats" ] }, "parameters": [ { "in": "path", "name": "stat_id", "required": true, "schema": { "type": "string", "minLength": 1 } } ] }, "/v2/webhooks": { "get": { "parameters": [ { "in": "query", "name": "page", "description": "The page number of users to be retrieved (for pagination)", "schema": { "type": "integer", "default": null, "nullable": true }, "required": false }, { "in": "query", "name": "limit", "description": "Number of results per page to return", "schema": { "type": "integer", "default": null, "nullable": true }, "required": false } ], "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhooksResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Return the list of webhooks registered", "description": "NOTE: if the endpoint is called by an authorized API key, return all webhook", "tags": [ "webhooks" ] }, "post": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } } } }, "summary": "Register a new webhook for a specific event", "tags": [ "webhooks" ] } }, "/v2/webhooks/{webhook_id}": { "get": { "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Return details about a specific webhook", "tags": [ "webhooks" ] }, "put": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest1" } } } }, "summary": "Change properties of a webhook", "description": "NOTE: in the arguments, we passed the partial parameter to WebhookSchema to remove the required\nrequirements from fields that are required during creation, because this is a modification endpoint.\nSo, events is not required BUT, if we specified it, it MUST specify the event_type; so, set partial\nonly to the other field, otherwise the partial-ness would be inherited from the nested schema that\nspecify the event. See https://marshmallow.readthedocs.io/en/stable/nesting.html#partial-loading", "tags": [ "webhooks" ] }, "delete": { "responses": { "204": { "description": "No Content" }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "summary": "Delete an existing webhook", "tags": [ "webhooks" ] }, "parameters": [ { "name": "webhook_id", "in": "path", "description": "The unique ID of webhook", "required": true, "schema": { "type": "integer", "minimum": 0 } } ] }, "/v2/webhooks/{webhook_id}/status": { "put": { "responses": { "422": { "$ref": "#/components/responses/UNPROCESSABLE_ENTITY" }, "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "default": { "$ref": "#/components/responses/DEFAULT_ERROR" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookStatusRequest" } } } }, "summary": "Change status of a webhook", "tags": [ "webhooks" ] }, "parameters": [ { "name": "webhook_id", "in": "path", "description": "The unique ID of webhook", "required": true, "schema": { "type": "integer", "minimum": 0 } } ] } }, "info": { "title": "Core API", "version": "1.0.0" }, "tags": [ { "name": "assistantsPrivate", "description": "Collection of assistant endpoints used by internal services only (not public)" }, { "name": "assistants", "description": "Collection of endpoints to handle vocal assistants operations" }, { "name": "base", "description": "Collection of endpoints to handle default base operations" }, { "name": "documents", "description": "Collection of endpoints to handle documents operations" }, { "name": "hk", "description": "Endpoints used with homekit" }, { "name": "monitors", "description": "Collection of endpoints to handle monitors operations" }, { "name": "rootPrivate", "description": "Root private endpoints" }, { "name": "root", "description": "Root endpoints" }, { "name": "stats", "description": "Stats endpoint to get statistics about different metrics" }, { "name": "webhooks", "description": "Collection of endpoints to handle webhooks" } ], "openapi": "3.0.2" }