uc-config 0.1.0

package/vendor/core-api.json

@@ -0,0 +1 @@
+{"openapi": "3.1.1", "info": {"title": "Remote Two/3 REST Core-API", "summary": "REST Core-API for Remote Two/3", "version": "0.46.0", "contact": {"name": "API Support", "url": "https://github.com/unfoldedcircle/core-api/issues", "email": "support@unfoldedcircle.com"}, "license": {"name": "Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)", "url": "https://creativecommons.org/licenses/by-sa/4.0/"}, "description": "The Unfolded Circle REST Core-API for Remote Two/3 (_UCR REST Core-API_ in short) allows to configure the remote and\nmanage custom resource files. Furthermore, API-keys for the WebSocket & REST APIs can be created.\n\n## Overview\n\nThe Unfolded Circle Remote Core-APIs consist of:\n- this REST API\n- the [UCR WebSocket Core-API](https://github.com/unfoldedcircle/core-api/tree/main/core-api/websocket),\n  providing asynchronous events.\n\nThe focus of the Core-APIs is to provide all functionality for the UI application and the web-configurator.  \nThey allow to interact with the Unfolded Circle remote-core service and take full control of its features.\n\nThe Core-APIs may also be used by other external systems and integration drivers, if specific configuration or\ninteraction features are required, which are not present in the [UCR Integration-API](https://github.com/unfoldedcircle/core-api/tree/main/integration-api).\n\n## Authentication\n\nAll API endpoints besides `/api/pub` are secured. Available authentication methods are:\n- `Basic Auth` for every request.  \n  This should only be used for simple testing. At the moment there's only a single user account available for the\n  web-configurator.\n  - User: `web-configurator`\n  - Password: generated pin shown in the remote-UI.\n- `Bearer Token` for every request.  \n  This is the preferred authentication method for external systems communicating with the UCR REST Core-API.\n  - See `/auth/api_keys` endpoints on how to create and manage API keys.\n  - Only the `admin` role is supported at the moment. More roles will be added in the future.\n  - Example for a curl request:  \n    `curl 'http://$IP/api/system' --header 'Authorization: Bearer $API_KEY'`\n- `Cookie` based session login with the `/api/pub/login` endpoint.  \n  This is the preferred method for web frontends like the web-configurator.\n\n## \ud83d\udea7 Missing Features\n\nThe following features will be continuously added (in no particular order):\n\n- Upload of custom certificate\n- Static network configuration\n\nPlease check the [core-api GitHub issues](https://github.com/unfoldedcircle/core-api/issues) for the current state. \n\n## API Versioning\n\nThe API is versioned according to [SemVer](https://semver.org/).  \nThe initial public release will be `1.0.0` once it is considered stable enough with some initial integration\nimplementations and developer examples.\n\n**Any major version zero (`0.y.z`) is for initial development and may change at any time!**  \nI.e. backward compatibility for minor releases is not yet established, anything MAY change at any time!\nWe try avoiding it, but it might still happen...\n"}, "servers": [{"url": "/api"}, {"url": "http://localhost:8080/api"}, {"url": "https://localhost:8443/api"}, {"url": "http://unfolded-simulator.local:8080/api"}, {"url": "https://unfolded-simulator.local:8443/api"}], "security": [{"basicAuth": []}, {"cookieAuth": []}], "tags": [{"name": "info", "description": "\ud83d\udc81 Public status information and health checks"}, {"name": "auth", "description": "\ud83d\udd10 Session authentication"}, {"name": "api-keys", "description": "\ud83d\udd11 API keys for authentication."}, {"name": "external-token", "description": "\ud83d\udc8e Credential management for external systems, including generic tokens and OAuth2 credentials."}, {"name": "resources", "description": "\ud83d\udd08 Media files handling, e.g. manage background images, icons or sound effects."}, {"name": "integrations", "description": "\ud83e\udde9 Integration handling"}, {"name": "entities", "description": "\ud83d\udcfa Common handling of configured entities like sending commands and modifying editable properties.  \nEntities are usually provided by integrations, except the special activity, macro and infrared-remote entities.\n"}, {"name": "activities", "description": "\ud83c\udf9b\ufe0f Combine multiple entities into an activity with optional on- & off-sequences, physical button mappings and a\ncustom user interface.\n"}, {"name": "macros", "description": "\ud83d\udd22 Macros execute a sequence of commands which is exposed as an entity command. Macros don't have a custom user\ninterface.\n"}, {"name": "infrared", "description": "\ud83c\udf08 Infrared code set lookup, custom IR code management and IR emitter devices.\n"}, {"name": "remotes", "description": "\ud83c\udfae Create BT- and IR-remote-entities. Customize user interface and button mappings for all remote-entities types\nincluding external remote-entities from integrations.\n"}, {"name": "profiles", "description": "\ud83d\udc64 User profile configuration with profiles, groups, pages"}, {"name": "cfg", "description": "\ud83d\udcdd Configuration settings"}, {"name": "dock", "description": "\ud83d\udef0 Docking station management, discovery and infrared testing functions"}, {"name": "system", "description": "\u2699\ufe0f System information and commands"}], "externalDocs": {"description": "Find out more about the Remotes", "url": "https://www.unfoldedcircle.com/"}, "paths": {"/pub/version": {"get": {"tags": ["info"], "summary": "Get version information about installed components.", "operationId": "getVersion", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VersionInfo"}}}}}, "security": []}}, "/pub/status": {"get": {"tags": ["info"], "summary": "Get status information about the system.", "operationId": "getStatus", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "object", "properties": {"memory": {"type": "object", "description": "Memory status", "properties": {"total_memory": {"type": "integer", "description": "Amount of available RAM in bytes"}, "available_memory": {"type": "integer", "description": "Amount of available RAM in bytes for (re)use"}, "used_memory": {"type": "integer", "description": "Amount of used RAM in bytes"}, "total_swap": {"type": "integer", "description": "SWAP size in bytes"}, "used_swap": {"type": "integer", "description": "Free SWAP in bytes"}}}, "load_avg": {"type": "object", "description": "System load average", "properties": {"one": {"type": "number", "description": "Average load within one minute"}, "five": {"type": "number", "description": "Average load within five minutes"}, "fifteen": {"type": "number", "description": "Average load within fifteen minutes"}}}, "filesystem": {"type": "object", "description": "Filesystem status", "properties": {"user_data": {"type": "object", "properties": {"available": {"type": "integer", "description": "Amount of available disk space in bytes"}, "used": {"type": "integer", "description": "Amount of used disk space in bytes"}}}}}}}}}}}, "security": []}}, "/pub/health_check": {"get": {"tags": ["info"], "summary": "Retrieve health check information about the system and running services.", "operationId": "healthCheck", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "object", "properties": {"db": {"$ref": "#/components/schemas/HealthStatus"}, "ui": {"$ref": "#/components/schemas/HealthStatus"}, "storage": {"$ref": "#/components/schemas/HealthStatus"}}}}}}, "500": {"$ref": "#/components/responses/Err500InternalServerError"}}, "security": []}}, "/pub/login": {"post": {"tags": ["auth"], "summary": "Log in and create session.", "description": "A successful login returns a session authentication cookie which need to be submitted in subsequent requests.  \nThe session ID is returned in a cookie named `id`.\n", "operationId": "login", "requestBody": {"required": true, "description": "A JSON object containing the username and password.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LoginRequest"}}}}, "security": [], "responses": {"200": {"description": "Successfully authenticated.", "headers": {"Set-Cookie": {"schema": {"type": "string", "examples": ["id=abcde12345; Path=/; HttpOnly"]}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "500": {"$ref": "#/components/responses/Err500InternalServerError"}}}}, "/pub/logout": {"post": {"tags": ["auth"], "summary": "Log out from session.", "description": "The session is removed and the session cookie named `id` is cleared.\n", "operationId": "logout", "parameters": [{"name": "id", "in": "cookie", "description": "Session cookie", "schema": {"type": "string"}}], "security": [{"cookieAuth": []}], "responses": {"200": {"description": "Successfully logged out.", "headers": {"Set-Cookie": {"schema": {"type": "string", "examples": ["id=; HttpOnly; Path=/; Max-Age=0; Expires=Sat, 26 Jun 2021 12:05:09 GMT"]}}}}, "500": {"$ref": "#/components/responses/Err500InternalServerError"}}}}, "/auth/api_keys": {"head": {"tags": ["api-keys"], "summary": "Get total number of available API keys.", "operationId": "getApiKeyCount", "parameters": [{"$ref": "#/components/parameters/active"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["api-keys"], "summary": "List available API keys.", "description": "This endpoint is only intended for a management UI and not for client access. The response contains a key\nidentifier in `key_id` which is required for further operations on the API key, like disabling or revoking it or\nadding a description.\n", "operationId": "getApiKeys", "parameters": [{"$ref": "#/components/parameters/active"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKeys"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["api-keys"], "summary": "Create an API key for the UCR APIs.", "description": "The returned API key in `api_key` is only visible in this response. Afterwards it cannot be retrieved anymore!\n\nThe newly created API key is usually not yet enabled for use and must first be approved by the user on the remote.\n\nThe required scopes must be provided. They let you specify what exactly a client needs to access.\nWhen the access token request is displayed to the remote user for approval, the requested scopes will be\ndisplayed to them.\n\nAn error is returned if an API key already exists for the provided `name`. To issue a new API key for the same\nname, the old token needs to be revoked first.\n", "operationId": "createApiKey", "requestBody": {"description": "Client information requesting access", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKeyRequest"}, "examples": {"default": {"value": {"name": "My integration", "scopes": ["admin"]}}}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKeyResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["api-keys"], "summary": "Delete all API keys.", "description": "This endpoint is only intended for a management UI and not for client access. The required `key_id` parameter is\nreturned in the `GET /auth/api_keys` response.\n", "operationId": "deleteAllApiKeys", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/auth/api_keys/{apiKeyId}": {"get": {"tags": ["api-keys"], "summary": "Get information about an API key.", "description": "The API key itself is non-retrievable. This function provides the access rights and validity of a defined API key.\n\nThis endpoint is only intended for a management UI and not for client access. The required `key_id` parameter is\nreturned in the `GET /auth/api_keys` response.\n", "operationId": "getApiKey", "parameters": [{"$ref": "#/components/parameters/api_key_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKey"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["api-keys"], "summary": "Update properties of an API key.", "operationId": "updateApiKey", "description": "Activate, deactivate, rename or set validity periods of an existing API key.\n\nNote: access scopes cannot be changed. This requires to revoke the API key and request a new one.\n\nThis endpoint is only intended for a management UI and not for client access. The required `key_id` parameter is\nreturned in the `GET /auth/api_keys` response.\n", "parameters": [{"$ref": "#/components/parameters/api_key_id"}], "requestBody": {"description": "Properties to update in the existing token.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKeyUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiKey"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["api-keys"], "summary": "Revoke an API key.", "description": "The API key will be deleted, no further access is possible.\n\nThis endpoint is only intended for a management UI and not for client access. The required `key_id` parameter is\nreturned in the `GET /auth/api_keys` response.\n", "operationId": "deleteApiKey", "parameters": [{"$ref": "#/components/parameters/api_key_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/auth/scopes": {"get": {"tags": ["api-keys"], "summary": "Get available access scopes.", "description": "Access scopes are used to create tokens for the WebSocket API.\n", "operationId": "getAccessScopes", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Scopes"}}}}}}}, "/auth/callback": {"get": {"tags": ["external-token"], "summary": "\ud83e\uddea Public callback endpoint for OAuth2 authorization responses.", "description": "OAuth2 authorization callback endpoint for the Authorization Code grant.\n\nThis endpoint is intended to be used as the redirect URI target for external systems that support OAuth2\nauthorization code flow. After the user authorizes the client at the external authorization server, the\nauthorization server redirects the user agent back with either:\n\n- a successful authorization response containing `code` and typically `state`, or\n- an error response containing `error` and optional error details.\n\nA successful callback contains `code`. Error callbacks contain `error` instead and do not include a usable\nauthorization code.\n\nThe callback is processed by the Remote to continue the OAuth2 flow and store the resulting OAuth2 token data for\nthe corresponding external system or integration driver.\n\nClients should not call this endpoint directly except for development or testing of OAuth2 flows.\n\nThe `state` parameter should be treated as an opaque value used for request correlation and CSRF protection.\nIf a `state` value was included in the authorization request, the authorization server must return that exact value\nin the callback response.\n\nThis endpoint implements the authorization response handling defined by OAuth 2.0, RFC 6749:\n- [Section 4.1: Authorization Code Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)\n- [Section 4.1.2: Authorization Response](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2)\n- [Section 4.1.2.1: Error Response](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.2.1)\n- [Section 10.12: Cross-Site Request Forgery](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12)\n\n### \ud83d\udea7 Unfolded Circle OAuth redirect service\n\nThe Remote does not have a web browser for the OAuth2 authorization flow, and it is usually not reachable on a\npublic address. To solve this, Unfolded Circle offers a static redirect page on a public address.\n\nIn practice, the authorization server redirects the user agent to the public Unfolded Circle redirect page first.\nThat page then forwards the callback parameters to the target Remote on the local network through the browser\nrunning on the user's device.\n\nThe redirect service is only responsible for browser-side forwarding of the callback. The Remote address is not\nstored server-side by Unfolded Circle; it is only kept in the user's browser.\n", "operationId": "oauth2Callback", "parameters": [{"name": "code", "in": "query", "description": "Authorization code returned by the OAuth2 authorization server on successful user authorization.", "schema": {"type": "string"}}, {"name": "state", "in": "query", "description": "Opaque state value returned by the authorization server. Used for request correlation and CSRF protection.", "schema": {"type": "string"}}, {"name": "error", "in": "query", "description": "OAuth2 authorization error code returned by the authorization server instead of an authorization code.", "schema": {"type": "string"}}, {"name": "error_description", "in": "query", "description": "Human-readable error description returned by the authorization server.", "schema": {"type": "string"}}, {"name": "error_uri", "in": "query", "description": "URI identifying a human-readable web page with additional information about the error.", "schema": {"type": "string"}}], "responses": {"200": {"description": "HTML response shown in the user's browser after the OAuth2 authorization callback has been processed or forwarded.", "content": {"text/html": {"schema": {"type": "string"}}}}}, "security": []}}, "/auth/external": {"get": {"tags": ["external-token"], "summary": "\ud83e\uddea List registered external systems.", "description": "An external system is a device or service that requires authentication. Integration drivers use external systems to\nauthenticate with services or devices that require either a long-lived token or an OAuth2 authorization code flow.\n\nExternal systems cannot be created manually. They are created automatically when an integration driver requests one of\nthe following driver features:\n\n- `auth.external_tokens`: enables generic token support for a local or custom integration driver.\n  - The provided secret is made available to the integration driver runtime as a credential file. This is typically a\n    long-lived access token.\n  - \u26a0\ufe0f External integration drivers cannot use this feature.\n- `auth.oauth2.authorization_code`: enables OAuth2 authorization code flow support for an integration driver.\n  - \ud83d\udea7 under development\n  - Only one OAuth2 application credential is supported per integration driver (token type `OAUTH2_APP`).\n    For example, a Spotify integration driver requires one OAuth2 application credential.\n  - Multiple OAuth2 token entries can be stored per integration driver (token type `OAUTH2_TOKEN`).\n    For example, multiple Spotify accounts can be linked to the same integration driver.\n\nIf an external system is associated with an integration driver, the returned `intg_driver_id` field contains the\nintegration driver ID.\n\nClients must not infer semantics from the `system` field value. It is an opaque external system identifier and may\nchange in the future.\n\nIf an expected external system identifier is not returned by this operation, requests to\n`/auth/external/{system}` using that identifier will return `404 Not Found`.\nA client should therefore either call this method before creating or updating credentials, or handle `404` responses\naccordingly to inform the user that the integration is not available on the Remote.\n\nThe `type`, `state`, and `intg` query parameters can be used to filter the returned external systems.\n- `type`: only external systems having at least one credential of the specified type are returned. This implies\n  `state=ACTIVE`.\n  - `TOKEN`: generic token, for example a long-lived access token.\n  - `OAUTH2_APP`: OAuth2 application credentials. Requires an associated integration driver and implies `intg=true`.\n  - `OAUTH2_TOKEN`: OAuth2 token data, typically including access token, refresh token, and related metadata.\n- `state`: filters external systems based on whether they currently have stored credentials.\n  - `ALL`: no filtering is performed. This is the default.\n  - `NEW`: only external systems without any stored credentials.\n  - `ACTIVE`: only external systems with at least one stored credential.\n- `intg`: only external systems associated with an integration driver are returned.\n\nThe `token_count` value reflects the applied `type` filter. If no `type` filter is specified, it contains the total\nnumber of stored credentials for the external system.\n\nPlease note that not all filter combinations are currently supported. Common use cases are:\n- Return all external systems: no query parameters, or `state=ALL`\n- Return external systems associated with an integration driver: `intg=true`\n- List external systems associated with an integration driver that do not yet have stored credentials: `intg=true&state=NEW`\n- List all OAuth2 application credentials: `type=OAUTH2_APP`. This implies `intg=true&state=ACTIVE`\n- List all generic tokens: `type=TOKEN`. This implies `state=ACTIVE`\n", "operationId": "getExternalSystems", "parameters": [{"$ref": "#/components/parameters/token_type"}, {"name": "state", "in": "query", "description": "Filter external systems by credential state.", "required": false, "schema": {"$ref": "#/components/schemas/ExtSystemState"}}, {"name": "intg", "in": "query", "description": "Only return external systems associated with an integration driver.", "required": false, "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalSystemInfos"}, "examples": {"OAuth2 App Credentials (type=OAUTH2_APP)": {"value": [{"system": "uc_spotify_driver", "name": "Household Account", "token_count": 1, "token_id": "1234....", "intg_driver_id": "uc_spotify_driver", "intg_name": {"en": "Spotify"}, "icon": "uc:music"}]}, "New External Systems (state=NEW)": {"value": [{"system": "test-driver", "name": "Foobar", "token_count": 0}, {"system": "uc_spotify_driver-dev", "name": "Spotify", "token_count": 0}]}, "External Systems for Integration Drivers with Generic Tokens (type=TOKEN&intg=true)": {"value": [{"system": "hass", "name": "Home Assistant", "token_count": 1, "intg_driver_id": "hass", "intg_name": {"en": "Home Assistant"}, "icon": "uc:integration"}]}}}}}}}, "delete": {"tags": ["external-token"], "summary": "Remove all external authentication credentials.", "description": "Management operation to delete all external access tokens. Attention: this cannot be reverted!\n", "operationId": "deleteAllExternalAccessTokens", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}}}}, "/auth/external/{system}": {"post": {"tags": ["external-token"], "summary": "\ud83e\uddea Create an external authentication credential.", "description": "This endpoint stores credentials for an external system, for example a generic access token, OAuth2 application\ncredentials, or OAuth2 token data.\n\nIt can be used by a client or integration workflow to provide credentials for the corresponding integration driver\ninstead of requiring the user to enter them manually.\n\nIf a credential with the same `name` already exists for the given system, the server returns `422 Unprocessable Entity`.\nTo replace an existing credential, use `PUT /auth/external/{system}/{tokenId}`.\n\n### Token type `TOKEN`\n\nThis is the default generic token type.\n\nRequired fields are:\n- `token_id`: the primary identifier within the external system. It must be unique within that system and must not end\n  in `-DATA` or `-URL`.\n- `name`: a friendly name to display in a user interface. It must be unique within that system.\n- `token`: the secret credential.\n\nThe `token` format depends on the external system and the integration driver. It can be a UUID, JWT, PEM\ncertificate, or any other representation required for authentication or communication with the external system.\n\n\u26a0\ufe0f `TOKEN` credentials can be used by built-in and custom integration drivers. External integration drivers cannot\naccess the secret token value.\n\n\u26a0\ufe0f The secret token value cannot be retrieved through the API after creation. It is only made available to the\ncorresponding integration driver runtime as a credential file.\n\nTo use generic external tokens, an integration driver must request the `auth.external_tokens` driver feature.\nIf enabled, an external system is created automatically with the `system` identifier matching the `driver_id`.\n\nUse `GET /auth/external` to retrieve the registered external systems.\n\nCredential files are created automatically in the corresponding integration driver runtime for a new `TOKEN` entry:\n- The `UC_TOKENS_HOME` environment variable specifies the directory containing the credential files.\n- The `token_id` value is used as the file name for the secret token.\n  - Example: for `token_id: foobar`, the secret token is available at `${UC_TOKENS_HOME}/foobar`.\n  - The file contains the `token` field value in plain text.\n- Optional files are created for the `url` and `data` fields:\n  - `{token_id}-URL` contains the `url` value. Example: `${UC_TOKENS_HOME}/foobar-URL`\n  - `{token_id}-DATA` contains the `data` value. Example: `${UC_TOKENS_HOME}/foobar-DATA`\n\n### Token type `OAUTH2_APP`\n\nThis token type stores OAuth2 application credentials consisting of the client ID and client secret.\n\nRequired fields are:\n- `name`: a friendly name to display in a user interface. It must be unique within that system.\n  This is typically the linked integration name or another identifier for the target application, for example an\n  account name.\n- `token_id`: OAuth2 client ID\n- `token`: OAuth2 client secret\n\nThe `url` and `data` fields are not used for OAuth2 application credentials.\n\n\u26a0\ufe0f The secret token value cannot be retrieved through the API after creation. It is only made available to the\ncorresponding integration driver runtime through the OAuth2-specific Integration API messages.\n\nTo use OAuth2 application credentials, an integration driver must request the\n`auth.oauth2.authorization_code` driver feature.\nIf enabled, an external system is created automatically with the `system` identifier matching the `driver_id`.\n\n### \ud83d\udea7 Token type `OAUTH2_TOKEN`\n\nThis token type stores OAuth2 token data returned by the authorization code flow, typically including an access token,\nrefresh token, and related metadata such as expiration information.\n\n`OAUTH2_TOKEN` entries are normally created automatically after a successful OAuth2 authorization code flow. For\ndevelopment and testing purposes, they can also be created manually.\n\nMultiple `OAUTH2_TOKEN` entries can be stored for the same OAuth2 application. For example, multiple Spotify accounts\ncan be linked to the same integration driver.\n\n\ud83d\udea7 For manual creation of `OAUTH2_TOKEN` entries, the request payload format is not yet finalized and should\n   currently be treated as implementation-specific. It will be documented later.\n", "operationId": "addExternalAccessToken", "parameters": [{"$ref": "#/components/parameters/system"}], "requestBody": {"description": "Credential to store for the external system.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalAccessTokenRequest"}}}, "required": true}, "responses": {"201": {"description": "Credential created successfully. Returns the token identifier.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalAccessTokenResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "head": {"tags": ["external-token"], "summary": "\ud83e\uddea Get total number of available credentials for an external system.", "description": "Returns the total number of stored credentials for the specified external system.\nUse the optional `type` query parameter to restrict the count to a single credential type.\n", "operationId": "getExternalAccessTokenCount", "parameters": [{"$ref": "#/components/parameters/system"}, {"$ref": "#/components/parameters/token_type"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["external-token"], "summary": "\ud83e\uddea List available credentials for an external system.", "description": "Lists stored credentials for the specified external system.\n\nUse the optional `type` query parameter to restrict the result to a single credential type.\nThe returned objects contain public metadata only. Secret credential values are never returned by the API.\n", "operationId": "getExternalAccessTokens", "parameters": [{"$ref": "#/components/parameters/system"}, {"$ref": "#/components/parameters/token_type"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalAccessTokens"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["external-token"], "summary": "Remove all credentials of an external system.", "description": "Stored runtime credential material for the corresponding integration driver is also removed.\nFor `TOKEN` credentials, this includes the mapped credential files.\n\n\u26a0\ufe0f The `delete_system` parameter is only intended for testing and development. This can put your system in an unstable state!\n", "operationId": "deleteExternalAccessTokensBySystem", "parameters": [{"$ref": "#/components/parameters/system"}, {"name": "delete_system", "in": "query", "description": "Also delete the external system entry after removing all associated credentials.", "required": false, "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/auth/external/{system}/{tokenId}": {"get": {"tags": ["external-token"], "summary": "\ud83e\uddea Get an external authentication credential.", "description": "Retrieve a stored credential for the specified external system and token identifier.\n\n\u26a0\ufe0f Only the public metadata of the credential is returned. The secret credential value cannot be retrieved through\nthe API after creation.\n\nFor `TOKEN` credentials, the secret value is made available to the corresponding integration driver runtime as a\ncredential file. For OAuth2-related credential types, secret values are made available through the corresponding\nOAuth2-specific integration mechanisms.\n", "operationId": "getExternalAccessToken", "parameters": [{"$ref": "#/components/parameters/system"}, {"$ref": "#/components/parameters/tokenId"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalAccessToken"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["external-token"], "summary": "\ud83e\uddea Replace an existing credential of an external system.", "description": "Replace an existing credential identified by the external system identifier and `tokenId`.\n\nThe request body uses the same schema as credential creation. The path parameter `tokenId` identifies the existing\ncredential to replace.\n\nFor `TOKEN` credentials, updated secret values are also propagated to the corresponding credential files in the\nintegration driver runtime. For OAuth2-related credential types, updated secret values are propagated through the\ncorresponding OAuth2-specific integration mechanisms.\n\nNotes:\n- The `token_id` field in the request body is ignored.\n- If `name` is changed, it needs to be unique within the `system`.\n", "operationId": "replaceExternalAccessToken", "parameters": [{"$ref": "#/components/parameters/system"}, {"$ref": "#/components/parameters/tokenId"}], "requestBody": {"description": "Credential data used to replace the existing external system credential.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalAccessTokenRequest"}}}, "required": true}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["external-token"], "summary": "Remove an external authentication credential.", "description": "No error is returned if the `tokenId` does not exist. `404` is only returned if the external system is not found.\n\nThe mapped credential files of the corresponding integration driver are also deleted.\n", "operationId": "deleteExternalAccessToken", "parameters": [{"$ref": "#/components/parameters/system"}, {"$ref": "#/components/parameters/tokenId"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/resources": {"get": {"tags": ["resources"], "summary": "Get supported media resource types.", "operationId": "getResourceTypes", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SupportedResources"}, "examples": {"default": {"value": [{"type": "Icon", "name": {"en": "Icon", "de": "Icon"}, "description": {"en": "User interface icons for entities and integrations. Icons must be of size 90x90 pixels and either in PNG or JPG format. Maximum size is 32 KB.", "de": "Icons f\u00fcr die Benutzeroberfl\u00e4che von Objekten und Integrationen. Die Icons m\u00fcssen 90x90 Pixel gross und im PNG oder JPG Format sein. Maximale Gr\u00f6sse ist 32 KB."}, "file_formats": ["png", "jpg"], "max_file_size": 32768, "max_count": 100, "image": {"sizes": [{"width": 90, "height": 90}]}}, {"type": "TvChannelIcon", "name": {"en": "TV channel icon", "de": "TV Sender Icon"}, "description": {"en": "User interface icons for TV channels. Icons must be of size 90x90 pixels and either in PNG or JPG format. Maximum size is 32 KB.", "de": "TV Sender Icons f\u00fcr die Benutzeroberfl\u00e4che. Die Icons m\u00fcssen 90x90 Pixel gross und im PNG oder JPG Format sein. Maximale Gr\u00f6sse ist 32 KB."}, "file_formats": ["png", "jpg"], "max_file_size": 32768, "max_count": 256, "image": {"sizes": [{"width": 90, "height": 90}]}}, {"type": "BackgroundImage", "name": {"en": "Background image", "de": "Hintergrund Bild"}, "description": {"en": "Background image for user interface profile pages. Images must be of size 275x480 pixels and either in PNG or JPG format. Maximum size is 1 MB.", "de": "Hintergrund Bild f\u00fcr Profil Seiten. Die Bilder m\u00fcssen 275x480 Pixel gross und im PNG oder JPG Format sein. Maximale Gr\u00f6sse ist 1 MB."}, "file_formats": ["png", "jpg"], "max_file_size": 1048576, "max_count": 30, "image": {"sizes": [{"width": 275, "height": 480}]}}, {"type": "Sound", "name": {"en": "Sound effect", "de": "Klangeffekt"}, "description": {"en": "User interface sound effects. Maximum size is 1 MB.", "de": "Klangeffekte f\u00fcr die Benutzeroberfl\u00e4che. Maximale Gr\u00f6sse ist 1 MB."}, "file_formats": ["wav"], "max_file_size": 1048576, "max_count": 50, "sound": {"bits": [8, 16], "channels": [1, 2], "sampling_rates": [11025, 22050, 44100]}}, {"type": "BtDeviceProfile", "name": {"en": "Bluetooth device profile", "de": "Bluetooth Ger\u00e4teprofil"}, "description": {"en": "Bluetooth peripheral device profile. Defines available HID commands like keyboard keys and consumer codes. Maximum size is 64 KB."}, "file_formats": ["json"], "max_file_size": 65536, "max_count": 100}]}}}}}}}, "delete": {"tags": ["resources"], "summary": "Delete all resources.", "description": "\u26a0\ufe0f All resources of all types are deleted if no resource-type query restriction is specified!\n", "operationId": "deleteAllResources", "parameters": [{"$ref": "#/components/parameters/resource_type_query"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}}}}, "/resources/{type}": {"head": {"tags": ["resources"], "summary": "Get total number of available resources of a given type.", "description": "The available resource types can be retrieved with the `GET /resources` endpoint.\n", "operationId": "getResourceTypeItemsCount", "parameters": [{"$ref": "#/components/parameters/resource_type"}, {"$ref": "#/components/parameters/query"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["resources"], "summary": "List available media resources of a given type.", "description": "The available resource types can be retrieved with the `GET /resources` endpoint.\n", "operationId": "getResourceTypeItems", "parameters": [{"$ref": "#/components/parameters/resource_type"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}, {"$ref": "#/components/parameters/query"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResourceItems"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["resources"], "summary": "Upload media or other resource files.", "description": "Upload one or more resource files as form-data. Files must conform to the given type according to the metadata\nreturned in `GET /api/resources`. E.g. an icon resource has other image size restrictions than a background image.\n\nThe file names are normalized (e.g. spaces replaced with underscores) and returned as resource identifiers.\n\nUploaded resources are verified, if they match expected formats. Status codes: \n- `400`: resource doesn't confirm to the expected parameters.\n- `422`: resource already exists with the same name. Already existing resource files are NOT overwritten.\n- `507`: insufficient storage to save a new resource.\n", "operationId": "uploadFile", "parameters": [{"$ref": "#/components/parameters/resource_type"}], "requestBody": {"content": {"multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"type": "string", "format": "binary"}}}}}}, "responses": {"201": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResourceItems"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}, "507": {"$ref": "#/components/responses/Err507InsufficientStorage"}}}, "delete": {"tags": ["resources"], "summary": "Delete all resources of a given type.", "operationId": "deleteResources", "parameters": [{"$ref": "#/components/parameters/resource_type"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/resources/{type}/{id}": {"get": {"tags": ["resources"], "summary": "Download a media resource.", "operationId": "getResource", "parameters": [{"$ref": "#/components/parameters/resource_type"}, {"$ref": "#/components/parameters/resource_id"}], "responses": {"200": {"description": "A resource file", "content": {"image/png": {"schema": {"type": "string", "format": "binary"}}, "image/jpg": {"schema": {"type": "string", "format": "binary"}}, "audio/wav": {"schema": {"type": "string", "format": "binary"}}, "application/octet-stream": {"schema": {"type": "string", "format": "binary"}}, "application/json": {"schema": {"type": "object"}}}}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["resources"], "summary": "Delete a media resource.", "operationId": "deleteResource", "parameters": [{"$ref": "#/components/parameters/resource_type"}, {"$ref": "#/components/parameters/resource_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/intg": {"head": {"tags": ["integrations"], "summary": "Get total number of configured and external integrations.", "operationId": "getIntegrationStatusCount", "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["integrations"], "summary": "Get overview of configured and external integrations.", "description": "Retrieve an overview of the configured integrations and their current connection state and all external\nintegrations which are ready to be configured. This overview is meant for an integration management frontend like\nthe web-configurator to avoid calling multiple API endpoints to gather integration driver and instance data.\n", "operationId": "getIntegrationStatus", "parameters": [{"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/IntegrationStatus"}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/intg/discover": {"get": {"tags": ["integrations"], "summary": "Get external integration driver discovery status.", "description": "Returns the current discovery status and the discovered integration drivers.\n\nUse the DELETE operation to stop an active discovery and PUT to start a new discovery.\n", "operationId": "getIntegrationDiscoveryStatus", "responses": {"200": {"description": "Integration discovery status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDiscoveryStatus"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "put": {"tags": ["integrations"], "summary": "Start discovery of external integration drivers.", "description": "Start integration driver discovery on the network with mDNS. By default the discovery automatically stops after\n30 seconds. Use the GET status request to check on discovered devices or DELETE to stop discovery.\n\nBy default only new integration drivers are returned. If a driver is already configured it will be omitted from the\nresults, unless the query parameter `new=false` is set.\n\n- Previously discovered integrations are removed, only newly discovered integrations will be returned.\n- Emits the WebSocket event `integration_discovery` with `event_type: START` when discovery starts.\n- For each discovered driver the WebSocket event `integration_discovery` with `event_type: DISCOVER` is emitted.\n", "operationId": "startIntegrationDiscovery", "parameters": [{"name": "timeout", "in": "query", "description": "Timeout in seconds.", "required": false, "schema": {"type": "integer", "format": "int32", "default": 30, "minimum": 1, "maximum": 300}}, {"name": "new", "in": "query", "description": "Only return new devices, filter out already configured integrations.", "required": false, "schema": {"type": "boolean", "default": true}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["integrations"], "summary": "Stop discovery of external integration drivers.", "description": "Stops the driver discovery and returns the current discovery status in the response.\n\nEmits the WebSocket event `integration_discovery` with `event_type: STOP`.\n", "operationId": "stopIntegrationDiscovery", "responses": {"200": {"description": "Integration discovery status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDiscoveryStatus"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/intg/discover/{driverId}": {"get": {"tags": ["integrations"], "summary": "Get integration driver discovery information.", "description": "Returns the discovered integration driver.\n", "operationId": "getDiscoveredIntegrationDriver", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "responses": {"200": {"description": "Integration discovery status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDiscovery"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["integrations"], "summary": "\ud83e\uddea Execute connection test and fetch metadata from discovered integration driver.", "description": "Perform a driver connection test with a discovered driver. If the driver requires a token, it must be specified in\nthe request body.\n\nResponse status codes:\n- `200`: successful operation: the connection test was successful and driver metadata could be retrieved.\n- `401` / `403`: driver authentication failed. Either the driver requires a token and it was not provided, or the \n         provided token was not valid.\n- `404`: discovered driver with `driver_id` not found. Check if the discovery result is still available and has not\n         been deleted. This can happen after a timeout since the discovery, or if the discovery result has been\n         cleared with starting a new discovery.\n- `503`: integration driver connection could not be established.\n", "operationId": "getDiscoveredIntgDriverMetadata", "parameters": [{"$ref": "#/components/parameters/driver_id"}, {"name": "timeout", "in": "query", "description": "Timeout in seconds.", "required": false, "schema": {"type": "integer", "format": "int32", "default": 5, "minimum": 3, "maximum": 60}}], "requestBody": {"required": false, "description": "Command payload", "content": {"application/json": {"schema": {"description": "Driver connection parameters.", "type": "object", "properties": {"connection": {"type": "object", "properties": {"driver_url": {"description": "Custom URL to connect to driver. If not specified the mDNS connection information is used.\n", "type": "string"}, "token": {"description": "Optional driver authentication token.\n", "type": "string", "maxLength": 2048}}}}}, "examples": {"Connection test without token and discovered driver url": {"value": {}}, "Connection test with token": {"value": {"connection": {"token": "0000"}}}, "Connection test with custom driver url": {"value": {"connection": {"driver_url": "ws://my-integration.local:8080"}}}}}}}, "responses": {"200": {"description": "Command response", "content": {"application/json": {"schema": {"type": "object", "properties": {"driver": {"$ref": "#/components/schemas/IntegrationDriver"}}, "required": ["driver"]}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "post": {"tags": ["integrations"], "summary": "Register a discovered integration driver.", "description": "Register a discovered integration driver:\n- establish communication with the driver.\n  - if the driver requires a password, it must be provided in the request.\n  - the discovered driver name and url can be overridden.\n- fetch metadata from the driver.\n- check compatability.\n- register the driver and connection parameters in the remote.\n\nAfter a successful registration the setup process of the driver can be started to configure the integration.\nThe required setup data is described in the returned `setup_data_schema` and the provided values by the user must\nbe passed to the `POST /intg/setup` operation.\n\nResponse status codes:\n- `400`: invalid data in request body.\n- `401` / `403`: driver authentication failed. Either the driver requires a token and it was not provided, or the \n         provided token was not valid.\n- `404`: no discovered driver found for given `driver_id`.\n- `409`: integration driver is already registered.\n- `503`: integration driver communication error. Either driver is not reachable or communication failed.\n", "operationId": "configureDiscoveredIntgDriver", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "requestBody": {"description": "Command payload", "content": {"application/json": {"schema": {"description": "Driver connection parameters.", "type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "driver_url": {"description": "Custom WebSocket URL of the driver, otherwise the discovered driver address is used.", "type": "string", "format": "uri", "maxLength": 2048}, "token": {"description": "Optional driver authentication token.\n", "type": "string", "maxLength": 2048}}}, "examples": {"Default": {"value": {}}, "Configure driver with custom url": {"value": {"driver_url": "ws://my-integration.local:8080"}}, "Configure driver with default name & url and custom token": {"value": {"token": "0000"}}, "Configure driver with custom name": {"value": {"name": {"en": "My integration", "de": "Meine Integration"}}}}}}}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDriver"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/intg/install": {"post": {"tags": ["integrations"], "summary": "\ud83e\uddea Upload and install a custom integration.", "description": "Install a custom integration driver from an integration driver installation archive.\n\n\u2139\ufe0f This is a synchronous operation which takes at least 10 seconds to complete for a small Node.js driver.\nLarger archives will require more time. This might change to async processing and background installation in the future. \n\nIntegration driver archive requirements:\n- TAR GZip archive (either .tgz or .tar.gz file suffix) with a maximum size of 100 MB.\n- In the root of the archive, there must be a `driver.json` file describing the custom integration driver.  \n  See `IntegrationDataMetadata` schema for the driver.json format.\n- The driver binary must be in the `./bin` subdirectory.\n  - Either a statically linked aarch64 executable named `driver`.\n  - Or a Node.js file named `driver.js`.\n- All application files must be in one of the following subdirectories, other locations are not accessible at runtime:\n  - `./bin`: application binary, usually only `driver`.\n  - `./config`: configuration data. Path is accessible with `UC_CONFIG_HOME` environment variable.\n  - `./data`: application data. Path is accessible with `UC_DATA_HOME` environment variable.\n\nRestrictions:\n- Maximum 10 custom integrations can be installed.\n- Only Node.js is supported besides a statically linked binary. Other runtimes are not supported at the moment.\n- The integration driver runs in a sandbox. Access to devices and the filesystem is restricted.\n- No symlinks are allowed. They are automatically removed during the installation.\n- Executable files are only allowed in the `./bin` directory.\n  - An integration driver should be limited to one process and not launch other processes.\n  - No other tools are provided in the runtime environment. E.g. there is no shell available and no other tools\n    like `cp` or `mv`.\n- Only the `config` and `data` directories are writeable and persisted between restarts.\n  - The `/tmp` directory can be used for small temporary files. Files are not persisted between restarts.\n- File access with relative paths between `bin`, `config`, and `data` is not possible.\n  - Environment variables must be used to retrieve the full path of these directories.\n    - `UC_CONFIG_HOME` and `HOME`: configuration directory.\n    - `STATE_DIRECTORY`: data directory.\n  - The returned path may not be stored, it may change with future software updates.\n\nExisting custom integrations can be updated by setting the `update` query parameter to `true`.\n- A custom integration must be installed having the same `driver_id`, otherwise error `404` is returned.\n- Existing configuration files are not replaced.\n  - It is recommended to not include dynamic configuration files in the archive. The integration should create them\n    at runtime and automatically migrate them if required.\n- All binary and data files are overwritten.\n\nTo delete a custom integration, use the regular endpoints to delete an integration instance and driver:\n- Delete integration `DELETE /api/intg/instances/:intgId`.\n- Delete driver and installation files: `DELETE /api/intg/drivers/:driverId`.\n\nError response codes:\n- `400`: invalid archive, missing data in archive or included metadata cannot be read.\n- `404`: custom integration not found for updating, there's no installed custom integration with the same `driver_id`. \n- `409`: custom integration is not compatible with the current firmware or the maximum amount of custom integration\n         installations has been reached.\n- `413`: archive is too large.\n- `422`: integration is already installed, or the `driver_id` has been used by another integration.\n- `503`: service unavailable, an installation is already running or a fatal error occurred at a previous\n         installation and the device needs to be restarted.\n- `507`: insufficient storage to upload and process installation archive.\n", "operationId": "installCustomIntegration", "parameters": [{"name": "update", "in": "query", "description": "Update an existing custom integration.", "required": false, "schema": {"type": "boolean"}}], "requestBody": {"content": {"multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"description": "TAR GZip Archive file with the custom integration. File extension must be `.tar.gz` or `.tgz`.", "type": "string", "format": "binary"}}}}}}, "responses": {"201": {"description": "Custom integration successfully installed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDriverInfo"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "413": {"$ref": "#/components/responses/Err413PayloadTooLarge"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}, "507": {"$ref": "#/components/responses/Err507InsufficientStorage"}}}}, "/intg/setup": {"get": {"tags": ["integrations"], "summary": "Get current integration setup processes.", "description": "Return a list of all active setup process identifiers. The returned ids can be used with the\n`/intg/setup/:id` endpoints to continue or abort a setup process.\n", "operationId": "getIntegrationSetupProcesses", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "string"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "post": {"tags": ["integrations"], "summary": "Start setting up a new integration driver.", "description": "Start a new setup process for the given integration driver and provided setup data, or reconfigure an existing\ndriver.\n\n- This operation immediately starts the driver communication and setup process.\n- There may only be one active setup process per driver, otherwise status code `409` is returned.\n\nThe returned `id` in the `IntegrationSetupInfo` response will be the identifier for the further setup operations\nwith the `/intg/setup/:driver_id` endpoints. Once the setup process is successfully finished, an integration instance is\ncreated. A setup process can be simple and fully automatic, but may also require user interaction and further\ncommunication with the `/intg/setup/:driver_id` endpoint.\n\nEmits the WebSocket event `integration_setup_change` with `event_type: START`.\n\nRequest body:\n- `name`: optional integration name. If not specified the name of the integration driver is used.\n- `setup_data`: optional driver setting values corresponding to the driver's `setup_data_schema` object.\n- `reconfigure`: set to true to reconfigure an already configured driver. The configuration options and behaviour\n  is driver dependent.\n\nResponse status codes:\n- `400`: invalid data in request body. E.g. setting the reconfigure flag for a new driver which is not yet configured.\n- `404`: specified `driver_id` in request body does not exist.\n- `409`: a setup process for the given `driver_id` already exists. Either continue or abort existing process.\n- `422`: the setup process cannot be used: either the integration is already configured or doesn't allow to be\n         set up again.  \n- `503`: integration driver communication error. Either driver is not reachable or communication failed.\n", "operationId": "setupIntegration", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateIntegrationSetup"}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationSetupInfo"}, "examples": {"default": {"value": {"id": "sim-test", "state": "SETUP"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["integrations"], "summary": "Abort and remove all setup processes.", "description": "Stop all setup processes at the next possible operation and remove all setup process information.  \nDepending on the integration driver, a started setup process cannot be aborted.\n\n\u26a0\ufe0f This stops all setup processes, not just for the current session!\n", "operationId": "stopAllIntegrationSetups", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/intg/setup/{driverId}": {"get": {"tags": ["integrations"], "summary": "Get integration driver setup status.", "description": "Poll operation to retrieve the current integration driver setup state. See the `state` and `error` fields in the\nresponse message. There are also WebSocket `integration_setup_change` event messages for state changes to avoid\npolling.\n\nDefined setup states:\n- `SETUP`: setup is running and configuring the integration. \n- `WAIT_USER_ACTION`: user input is required to continue the setup process. See `require_user_action` in response\n   for the required user input. Provide the requested data with the `PUT` operation.\n- `OK`: setup process has been completed successfully, the integration driver can now be used.\n- `ERROR`: the setup process failed. Check the `error` field for more information.\n", "operationId": "getIntegrationSetupStatus", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationSetupInfo"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["integrations"], "summary": "Provide requested integration setup data.", "description": "Set required data to configure the integration driver or continue the setup process.\n\nDefined user actions to set in the request body `action` field:\n- `input_values`: if the user was requested to enter settings, e.g. connection or credential parameters to a device\n  or service.\n- `confirm`: response to the user action `confirmation`. Set to `true` if the user had to perform an action like\n  pressing a button on a device and then confirms the action with continuing the setup process.  \n  The `false` value is prepared for yes / no choices.\n\nThe `state` field in the response message indicate the current state of the setup process. Use the `GET` operation\nto poll for state updates or listen to the corresponding WebSocket `integration_setup_change` event messages with\n`event_type: SETUP`.\n", "operationId": "setIntegrationUserData", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "requestBody": {"content": {"application/json": {"schema": {"oneOf": [{"type": "object", "properties": {"input_values": {"$ref": "#/components/schemas/SettingsValues"}}, "required": ["input_values"]}, {"type": "object", "properties": {"confirm": {"type": "boolean"}}, "required": ["confirm"]}]}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationSetupInfo"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["integrations"], "summary": "Abort the integration driver setup process.", "description": "Stop the setup process at the next possible operation and remove the setup process information.  \nTo start a new setup process, use the `POST /intg/setup` operation again.\n\nDepending on the integration driver, a started setup process cannot be aborted.\n\nEmits the WebSocket event `integration_setup_change` with `event_type: STOP`.\n", "operationId": "stopIntegrationSetup", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/intg/drivers": {"head": {"tags": ["integrations"], "summary": "Get total number of registered integration drivers.", "operationId": "getIntegrationDriversCount", "parameters": [{"name": "driver_type", "in": "query", "description": "Filter by driver type.", "schema": {"type": "string", "enum": ["LOCAL", "CUSTOM", "EXTERNAL"]}}, {"$ref": "#/components/parameters/enabled"}, {"$ref": "#/components/parameters/instantiable"}, {"$ref": "#/components/parameters/single_device"}, {"$ref": "#/components/parameters/has_instances"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["integrations"], "summary": "Get all registered integration drivers.", "description": "Returns an overview of all registered drivers. To retrieve all driver data use `/intg/drivers/{driverId}`.\n", "operationId": "getIntegrationDrivers", "parameters": [{"name": "driver_type", "in": "query", "description": "Filter by driver type.", "schema": {"type": "string", "enum": ["LOCAL", "CUSTOM", "EXTERNAL"]}}, {"$ref": "#/components/parameters/enabled"}, {"$ref": "#/components/parameters/instantiable"}, {"$ref": "#/components/parameters/single_device"}, {"$ref": "#/components/parameters/has_instances"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDrivers"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["integrations"], "summary": "\ud83e\uddea Manually register a new integration driver.", "description": "A driver provides the connection parameters and optional setup configuration for an integration driver.\n\nRegistering a driver requires that the driver is running and responding to requests on the given URL. The driver\ndetails will be fetched and stored in the Remote.\n\nDepending on the driver capabilities it either provides a single access point to the provided entities, or exposes\nmultiple devices, each with its own unique set of entities. The former could for example be used to provide GPIO\naccess of a Raspberry Pi or gather all supported devices it is able to interact with (e.g. network sensors, light\nswitches etc.). The more capable multi-device mode is suited to bridge home automation hubs where multiple\ninstances should be supported.\n\nOnce a driver is registered, one or more integration instances must be configured to interact with the driver.  \nFor simple integration drivers there's a 1:1 relationship between an instance and driver. For multi-device drivers, \neach device corresponds to an integration instance.\n\nIt is recommended to manually set a unique and human-readable driver identifier in `driver_id`. Otherwise a UUID\nwill be assigned. The `driver_id` is required for all further interactions with the driver, like creating a runtime\ninstance to connect to the driver and fetch available entities.\n", "operationId": "registerIntegrationDriver", "requestBody": {"description": "Integration driver data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDriverRequest"}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the created integration driver in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDriver"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/intg/drivers/{driverId}": {"get": {"tags": ["integrations"], "summary": "Get integration driver metadata.", "description": "Returns the full data of an integration driver, except the authentication token for external clients.\n", "operationId": "getIntegrationDriver", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDriver"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["integrations"], "summary": "Modify connection parameters of an external integration driver.", "description": "Update connection settings of an external integration driver if the URL or access token has changed. The new\nsettings are immediately applied and the driver communication verified. This might take a few seconds.  \nThe driver's own optional configuration settings cannot be applied with this operation and are configured during\nthe setup process, or through the integration instance.\n\n- Only external integration drivers can be modified. Otherwise `400` (Bad Request) is returned.\n- Connection settings are tested and applied against the driver.\n  - `503` (Service Unavailable) is returned if the driver communication fails.\n  - If the driver is not active, the settings are only applied and not tested! This is for development use only.\n- See request description on how to update or remove an existing setting.\n", "operationId": "updateIntegrationDriver", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "requestBody": {"description": "Entity data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDriverUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation returning the updated integration driver in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationDriver"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "put": {"tags": ["integrations"], "summary": "Execute a command on an integration driver.", "description": "Available driver commands:\n- `CONNECTION_TEST`: perform a driver connection test with the connection parameters in the payload.\n- `START`: Manually start an integration driver.\n- `STOP`: Manually stop a driver to disable all integration instances processing.\n\nResponse status codes:\n- `200`: successful operation, e.g. the connection test was successful.\n- `400`: bad request, e.g. connection parameters missing for connection test command.\n- `503`: integration driver connection could not be established.\n\nIf a driver is enabled it will start automatically. Manually starting and stopping a driver is for testing purposes\nand setting up new drivers in the web-configurator.\n", "operationId": "integrationDriverCommand", "parameters": [{"$ref": "#/components/parameters/driver_id"}, {"name": "cmd", "in": "query", "description": "Command to execute.", "required": true, "schema": {"type": "string", "enum": ["CONNECTION_TEST", "START", "STOP"]}}], "requestBody": {"required": false, "description": "Command payload", "content": {"application/json": {"schema": {"description": "Driver connection parameters for `CONNECTION_TEST` command only.", "type": "object", "properties": {"driver_url": {"description": "WebSocket URL of the driver.", "type": "string", "format": "uri", "maxLength": 2048}, "token": {"description": "Optional driver authentication token.\n", "type": "string", "maxLength": 2048}}, "required": ["driver_url"]}, "examples": {"Connection test": {"value": {"driver_url": "ws://192.168.1.200:8000/ws", "token": "0000"}}}}}}, "responses": {"200": {"description": "Successful operation, returns the `IntegrationDriver` object for the `CONNECTION_TEST` command, otherwise the\ncommon `ApiResponse` object.\n", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/IntegrationDriver"}, {"$ref": "#/components/schemas/ApiResponse"}]}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "post": {"tags": ["integrations"], "summary": "Create a new integration instance from driver.", "description": "Create an integration driver instance and associate it with the driver.  \nFor simple integration drivers there's a 1:1 relationship only between an instance and driver.\nFor multi-device drivers, each device corresponds to an integration instance.\n\n- the `integration_id` is automatically created by the system to make it unique over all integrations.\n- for multi-device drivers the `device_id` must be specified and may not already exist in another instance of the\n  same driver.\n- the driver's name is used by default if `name` isn't specified.\n- the instance is active by default if `enabled` isn't specified.\n", "operationId": "createIntegration", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "requestBody": {"description": "Integration instance data.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationUpdate"}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the created integration instance in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Integration"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["integrations"], "summary": "Remove an integration driver.", "description": "Unloads and deletes an integration driver with all instances and provided entities.\n\n\u26a0\ufe0f **Attention**:\n- All references to the integration driver will be removed! This includes all driver instances,\nprovided entities and their references in profile pages and groups.\n- If the driver is a custom installed driver, the driver will be removed from the remote, including all\nconfiguration settings.\n- If an external access token system has been created for the driver, it will be removed as well, including all\n  associated tokens!\n", "operationId": "deleteIntegrationDriver", "parameters": [{"$ref": "#/components/parameters/driver_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/intg/instances": {"head": {"tags": ["integrations"], "summary": "Get total number of integration instances.", "operationId": "getIntegrationsCount", "parameters": [{"$ref": "#/components/parameters/enabled"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["integrations"], "summary": "Get all integration instances.", "operationId": "getIntegrations", "parameters": [{"$ref": "#/components/parameters/enabled"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Integrations"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["integrations"], "summary": "Connect or disconnect all integration instances.", "description": "Execute a command on all active integration instances:\n\n- `connect`: requests all enabled integrations to establish a session to the integration driver and start processing\n  events.  \n  Use `GET /intg/instances` or `GET /intg/instances/{intgId}` to check on the connection status.\n- `disconnect`: disconnects all active integration driver sessions.\n", "operationId": "executeCommandOnAllIntegrations", "parameters": [{"name": "cmd", "in": "query", "description": "Command to execute.", "required": true, "schema": {"type": "string", "enum": ["CONNECT", "DISCONNECT"]}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/intg/instances/{intgId}": {"get": {"tags": ["integrations"], "summary": "Get an integration instance.", "operationId": "getIntegration", "parameters": [{"$ref": "#/components/parameters/integration_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Integration"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["integrations"], "summary": "Modify a configured integration instance.", "description": "Modify one or several properties of an integration instance.  \nSee update model description on how to update or delete an existing property.\n\nThe integration driver of an instance cannot be changed and will be ignored if provided in the request.\n", "operationId": "updateIntegration", "parameters": [{"$ref": "#/components/parameters/integration_id"}], "requestBody": {"description": "Integration instance data.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntegrationUpdate"}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the updated integration instance in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Integration"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["integrations"], "summary": "Remove an integration instance.", "description": "Unloads and deletes an integration instance.\n\n**Attention: all references to the integration instance will be removed! This includes configured entities and \ntheir references in profile pages and groups.**\n", "operationId": "deleteIntegration", "parameters": [{"$ref": "#/components/parameters/integration_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["integrations"], "summary": "Connect or disconnect an integration instance.", "description": "Exectue a command on the integration instance:\n\n- `connect`: establish a session to the integration driver and start processing events.  \n  Use `GET /intg` or `GET /intg/instances/{intgId}` to check on the connection status.\n- `disconnect`: disconnect from the driver and stop processing events.\n", "operationId": "executeIntegrationCommand", "parameters": [{"$ref": "#/components/parameters/integration_id"}, {"name": "cmd", "in": "query", "description": "Command to execute.", "required": true, "schema": {"type": "string", "enum": ["CONNECT", "DISCONNECT"]}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/intg/instances/{intgId}/entities": {"get": {"tags": ["integrations"], "summary": "Get available entities from integration instance.", "description": "Retrieve the available entities provided by the integration instance.\n\nBy default only the entities are returned which are not yet configured. Use the `filter` query to include all or\nonly the already configured entities.\n\nAvailable entities can be searched and filtered by one or multiple entity types. The text search searches in the\nentity name, entity identifier and area.\n", "operationId": "getAvailableEntitiesFromInstance", "parameters": [{"$ref": "#/components/parameters/integration_id"}, {"name": "reload", "in": "query", "description": "Force reload available entities from driver.", "required": false, "schema": {"type": "boolean", "default": false}}, {"name": "filter", "in": "query", "description": "Filter available entities.", "required": false, "schema": {"type": "string", "default": "NEW", "enum": ["NEW", "CONFIGURED", "ALL"]}}, {"$ref": "#/components/parameters/entity_types"}, {"$ref": "#/components/parameters/query"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/AvailableEntity"}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["integrations"], "summary": "Configure multiple available entities.", "description": "Configure multiple new UC Remote entities from available integration entities. Once configured, the entities will\nno longer show up as an available entity (unless the `filter=ALL` query parameter is set).\n\nAn empty request body array will configure all available entities.\n\nUse endpoint `/intg/instances/{intgId}/entities/{entityId}` to configure a single entity and optionally rename it\nor change its icon.\n\nThis is a best effort operation:\n- if an entity is already configured, it is ignored and not returned in the response.\n- unknown entity identifiers are ignored, no error is returned\n\nEvery newly configured entity will trigger an `entity_change` event.\n", "operationId": "configureEntitiesFromIntegration", "parameters": [{"$ref": "#/components/parameters/integration_id"}], "requestBody": {"description": "Entity identifiers.", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "string"}}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the configured entity identifiers in the response.", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "string"}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/intg/instances/{intgId}/entities/{entityId}": {"post": {"tags": ["integrations"], "summary": "Configure an available entity.", "description": "Configure a new UC Remote entity from an available integration entity. Once configured, the entity will no longer\nshow up as available entity (unless the `filter=ALL` query parameter is set).\n\nThe entity `name`, `icon` and `description` fields may be changed. If not specified in the request the values from\nthe available entity are used.\n", "operationId": "configureEntityFromIntegration", "parameters": [{"$ref": "#/components/parameters/integration_id"}, {"$ref": "#/components/parameters/entity_id"}], "requestBody": {"description": "Entity data.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EntityUpdateRequest"}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the configured entity in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Entity"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}}, "/entities": {"head": {"tags": ["entities"], "summary": "Get total number of configured entities.", "operationId": "getEntityCount", "parameters": [{"$ref": "#/components/parameters/entity_types"}, {"$ref": "#/components/parameters/integration_ids"}, {"$ref": "#/components/parameters/exclude"}, {"$ref": "#/components/parameters/query"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["entities"], "summary": "Search and retrieve configured entities.", "description": "Returns all configured and loaded entities.\n\nEntities can be searched and filtered by one or multiple types and integrations. The text search searches in the\nentity name, entity identifier and integration name.\n\nThe `exclude` query parameter allows to exclude entities defined in an activity, macro, profile page or group.\nSupported exclusions:\n- activity- or macro-entity ID: all included entities\n- profile page_id: defined entities in the page\n- profile group_id: defined entities in the group\n\nNotes:\n- Mixing activity/macro and page/group identifiers is not supported!\n- All non-command entities are also filtered out if an activity or macro identifier is specified.\n", "operationId": "getEntities", "parameters": [{"$ref": "#/components/parameters/entity_types"}, {"$ref": "#/components/parameters/integration_ids"}, {"$ref": "#/components/parameters/exclude"}, {"$ref": "#/components/parameters/query"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Entities"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "delete": {"tags": ["entities"], "summary": "Remove configured entities.", "description": "Unloads and deletes multiple configured entities, either by integration identifier or by entity identifiers.\nIf a deleted entity is still provided from an integration, it can be reused and will show up again as\navailable entity from its integration.\n\n\u26a0\ufe0f An empty `entity_ids` array will delete all configured entities!\n\nAll references to the configured entities will be removed from profile pages and groups.\n\nThis is a best effort operation:\n- unknown entity identifiers are ignored, no error is returned\n\nDeleted entities will trigger an `entity_change` event with `event_type: DELETE`. If a large amount of entities\nare deleted, a single, generic `entity_change` event might be sent instead (without an `entity_id` field).\n", "operationId": "deleteEntities", "requestBody": {"description": "Integration or entity identifiers.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EntityDeleteRequest"}, "examples": {"by integration": {"value": {"integration_id": "hass.main"}}, "by entity identifiers": {"value": {"entity_ids": ["hass.main.sensor.1", "hass.main.sensor.2", "hass.main.light.1"]}}, "all entities": {"value": {"entity_ids": []}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/entities/{entityId}": {"get": {"tags": ["entities"], "summary": "Get a configured entity.", "operationId": "getEntity", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Entity"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["entities"], "summary": "Modify a configured entity.", "operationId": "updateEntity", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"description": "Entity data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EntityUpdateRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful operation returning the configured entity in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Entity"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["entities"], "summary": "Remove a configured entity.", "description": "Unloads and deletes a configured entity. If the entity is still provided from an integration it can be reused and\nwill show up again as available entity from its integration.\n\nAll references to the configured entity will be removed from profile pages and groups.\n", "operationId": "deleteEntity", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/entities/{entityId}/command": {"put": {"tags": ["entities"], "summary": "Execute an entity command.", "operationId": "executeEntityCommand", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"description": "Command data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EntityCommand"}}}, "required": true}, "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}}, "/entities/{entityId}/media/browse": {"get": {"tags": ["entities"], "summary": "\ud83d\udd0d Browse media containers.", "description": "This endpoint allows browsing media containers within supported media-player entities.\n\nThe `media_id` and `media_type` parameters are optional and can be used to restrict browsing to a specific media item\nor content type. Both fields can be returned in the browse response on the root item and on every child item to describe\nwhere the item lives in the provider\u2019s hierarchy and how it can be addressed later. For example, for playback or further\nbrowsing.\n\n**Important:** When using `media_id` and `media_type` values in further calls, they must match the values returned in\nthe previous `media_browse` response exactly. If an empty text (`\"\"`) is returned as value, that exact\nempty text must be sent back on subsequent requests. An empty text does not mean \"no value.\"\n\nA `media_id` or `media_type` field may only be omitted from a request if it was not present in the response at all\nor if it was explicitly set to `null` in the browse response.\n\nThe `stable_ids` query parameter is a hint that the client requires stable media identifiers in the returned\n`media_id` and `media_type` fields. Certain media providers may not support stable identifiers, but the integration\nmight be able to use a workaround generating stable identifiers on the client side.\n\nRoon is such an example, which generates new media keys for every new browse or search request. Use cases like    \n\"select an identifier of my favorite playlist, so I can still play it next month\" aren't possible with changing\nidentifiers. As a workaround, the integration driver returns a path structure (`Library/Playlists/Favorite Songs`)\nthat is resolved when playing an item.\n\nThe paging query parameters can be used to retrieve a specific page of media items and to limit result size:\n\n- `limit`: Maximum number of items to return per page. Default is 10.\n- `page`: 1-based page index. Default is 1.\n\nCommon error status codes:\n- `400 Bad Request`: if the query is invalid, for example if `media_type` is missing for a content specific query.\n- `404 Not Found`: if the entity does not exist or is not a media-player entity.\n- `408 Request Timeout`: if the media browse service is not responding.\n- `409 Conflict`: if the media-player entity does not support media browsing.\n- `500 Internal Server Error`: if an internal error occurred.\n- `503 Service Unavailable`: if the media browse service is unavailable or not supported for the given location specified in `media_id` and `media_type`.\n", "operationId": "browseMedia", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/media_id"}, {"$ref": "#/components/parameters/media_type"}, {"$ref": "#/components/parameters/stable_ids"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MediaBrowseResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "408": {"$ref": "#/components/responses/Err408RequestTimeout"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "500": {"$ref": "#/components/responses/Err500InternalServerError"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/entities/{entityId}/media/search": {"get": {"tags": ["entities"], "summary": "\ud83d\udd0d Search for media items.", "description": "This endpoint allows searching for media within supported media-player entities.\n\nThe `media_id` and `media_type` parameters behave the same as in the browse endpoint: they can be used to restrict the\nsearch to a specific container or content type.\n\nA `media_id` or `media_type` field may only be omitted from a request if it was not present in the response at all\nor if it was explicitly set to `null` in the search response.\n\nThe `stable_ids` query parameter is a hint that the client requires stable media identifiers in the returned\n`media_id` and `media_type` fields. Certain media providers may not support stable identifiers, but the integration\nmight be able to use a workaround generating stable identifiers on the client side. See browse endpoint for more\ninformation.\n\nThe paging query parameters can be used to retrieve a specific page of media items and to limit result size:\n\n- `limit`: Maximum number of items to return per page. Default is 10.\n- `page`: 1-based page index. Default is 1.\n\nCommon error status codes:\n- `400 Bad Request`: if the query is invalid, for example if `media_type` is missing for a content specific query.\n- `404 Not Found`: if the entity does not exist or is not a media-player entity.\n- `408 Request Timeout`: if the media search service is not responding.\n- `409 Conflict`: if the media-player entity does not support media searching.\n- `500 Internal Server Error`: if an internal error occurred.\n- `503 Service Unavailable`: if the media search service is unavailable or not supported for the given location specified in `media_id` and `media_type`.\n", "operationId": "searchMedia", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"name": "q", "in": "query", "description": "The search string.", "required": true, "schema": {"type": "string", "maxLength": 255}}, {"$ref": "#/components/parameters/media_id"}, {"$ref": "#/components/parameters/media_type"}, {"name": "media_classes", "in": "query", "description": "Optional media classes to filter the results. Separate multiple classes with a comma.", "required": false, "schema": {"type": "string"}}, {"name": "artist", "in": "query", "description": "Optional artist filter.", "required": false, "schema": {"type": "string", "maxLength": 255}}, {"name": "album", "in": "query", "description": "Optional album filter.", "required": false, "schema": {"type": "string", "maxLength": 255}}, {"$ref": "#/components/parameters/stable_ids"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MediaSearchResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "408": {"$ref": "#/components/responses/Err408RequestTimeout"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "500": {"$ref": "#/components/responses/Err500InternalServerError"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/activities": {"head": {"tags": ["activities"], "summary": "Get total number of activity entities.", "description": "The total number of available activities are returned in the `Pagination-Count` header. This allows to prepare the\nretrieval of the activities with the `GET` operation and paging parameters.\n\nThe optional text search query searches in the activity name and activity identifier.\n", "operationId": "getActivityCount", "parameters": [{"name": "in_group", "in": "query", "description": "Only activities in any activity group", "required": false, "schema": {"type": "boolean"}}, {"name": "group_id", "in": "query", "description": "Only activities in this activity group", "required": false, "schema": {"$ref": "#/components/schemas/SimpleId"}}, {"$ref": "#/components/parameters/query"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["activities"], "summary": "Get activity entities overview with paging.", "description": "Returns an overview of all defined activities with the given paging parameters. Use the `HEAD` operation to retrieve\nthe total number of defined activities.\n\nThe optional text search query searches in the activity name and activity identifier.\n\nThe overview information doesn't include all details of an activity. The full activity information is retrievable\nwith `/activities/{entityId}`.\n", "operationId": "getActivities", "parameters": [{"name": "in_group", "in": "query", "description": "Only activities in any activity group", "required": false, "schema": {"type": "boolean"}}, {"name": "group_id", "in": "query", "description": "Only activities in this activity group", "required": false, "schema": {"$ref": "#/components/schemas/SimpleId"}}, {"$ref": "#/components/parameters/query"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Activities"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "post": {"tags": ["activities"], "summary": "Create a new activity entity.", "description": "Create a new entity of type `activity`. An activity entity is a special internal entity without association to an\nintegration driver.\n\nTo create a new activity at least a name must be provided. The `icon`, `description` and `options.entity_ids`\nare optional and can be set later with the `PATCH` update operation.\n\nWhen setting a text in a multilingual field, like name or description, the default `en` identifier should always be\nincluded.\n\nAn activity can be cloned from another activity-, macro- or remote-entity identifier in `clone_from`. \nAll applicable configuration will be copied, except a new activity name must be specified. The `icon` and\n`description` fields can still be specified and will override the copied data. The `options.entity_ids` is\nnot allowed when cloning data, additional entities can be added later with the `PATCH` update operation.\n\nThe `entity_ids` may be omitted when creating a new activity and specified later when updating the activity.\n\nThe newly created activity will automatically be included in the default activity group (requires Core version 0.64\nor newer).\n", "operationId": "createActivity", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityCreate"}, "examples": {"simple": {"value": {"name": {"en": "My new activity"}}}, "activity with icon and description": {"value": {"name": {"en": "My new activity"}, "icon": "uc:bell", "description": {"en": "Testing the activity feature"}}}, "clone": {"value": {"name": {"en": "My cloned activity"}, "clone_from": "uc.main.activity.watch-tv"}}}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Activity"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["activities"], "summary": "Delete all activity entities.", "description": "\u26a0\ufe0f All defined activities will be irrevocably deleted!\n", "operationId": "deleteAllActivities", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/activities/{entityId}": {"get": {"tags": ["activities"], "summary": "Get an activity by its entity_id.", "description": "Returns all the information required to manage an existing activity. The included entities are enriched with `name`,\n`icon`, `entity_type`, available commands and if the entity is still available or has been removed since the\nactivity was defined.\n\nThe available entity commands are divided into:\n- `entity_commands`: regular entity commands as defined in the [entity documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities).\n   The identifier refers to the common entity command definitions, which describe all required parameters for \n   defining a command. This includes the mandatory `cmd_id` name and optional parameters.\n\n   \ud83d\udc77 TODO endpoint to retrieve entity command definitions.\n- `simple_commands`: additional, simple dynamic commands of an entity. Like infrared code commands of a\n   remote-entity. A simple command relates directly to the `cmd_id` attribute when executing a command and there's\n   no further mapping as for _entity_commands_.\n", "operationId": "getActivity", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Activity"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["activities"], "summary": "Update an activity entity.", "operationId": "updateActivity", "description": "Update one or multiple properties of an activity. The omitted properties are ignored and not deleted. To clear an\narray simply provide an empty array.\n\n- Button mappings are configured with the dedicated `/activities/{entityId}/buttons` and\n`/activities/{entityId}/buttons/{button}` endpoints.\n- The user interface is configured with the dedicated `/activities/{entityId}/ui`, `/activities/{entityId}/ui/pages`\n  and `/activities/{entityId}/ui/pages/{pageId}` endpoints.\n- Sequence-commands are composed of command definitions (see description of `entity_commands` and\n  `simple_commands` in GET operation). The `entity_id` and `cmd_id` attributes are always required. The `params`\n  object is only required for `entity_commands` having parameters. \n- The special `\"type\": \"delay\"` command is not described in the entity command definitions and can only be used in\n  sequences.\n", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"description": "Properties to update in the existing activity.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Activity"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Delete an activity entity.", "description": "\u26a0\ufe0f The given activity is irrevocably deleted.\n", "operationId": "deleteActivity", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/activities/{entityId}/buttons": {"get": {"tags": ["activities"], "summary": "Get the physical button mappings.", "operationId": "getActivityButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["activities"], "summary": "Merge multiple physical button mappings.", "description": "Update multiple button mappings at once. This merges the provided mappings with the existing mappings.\nIf a button object is provided it will be added to the mappings, or an existing mapping be updated.\nIf a short or long press entity command is missing in the update, the existing command will be kept.\n", "operationId": "mergeActivityButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["activities"], "summary": "Replace physical button mappings.", "description": "Replace all button mappings with the provided mappings.\n", "operationId": "updateActivityButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Reset the physical button mappings to their default state.", "description": "An automatic mapping of common functions to the physical buttons is performed. This depends on the chosen entities,\ne.g. an audio device will map the volume up & down keys and a TV or set-top box will map the channel up & down\ncommands.\n\n\u26a0\ufe0f The previous customization of the physical button mapping is irrevocably deleted.\n", "operationId": "resetActivityButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/activities/{entityId}/buttons/{buttonId}": {"get": {"tags": ["activities"], "summary": "Get a physical button mapping.", "operationId": "getActivityButtonMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMapping"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["activities"], "summary": "Update a physical button mapping.", "description": "Update the button mapping for either a short- or a long-press.\n", "operationId": "updateActivityButtonMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}], "requestBody": {"content": {"application/json": {"schema": {"oneOf": [{"type": "object", "properties": {"short_press": {"$ref": "#/components/schemas/EntityCommand"}}, "required": ["short_press"]}, {"type": "object", "properties": {"long_press": {"$ref": "#/components/schemas/EntityCommand"}}, "required": ["long_press"]}]}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMapping"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Remove a physical button mapping.", "description": "\u26a0\ufe0f The previous customization of the physical button mapping is irrevocably deleted.\n", "operationId": "deleteActivityButtonMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/activities/{entityId}/buttons/{buttonId}/{buttonPress}": {"get": {"tags": ["activities"], "summary": "Get a button press mapping.", "operationId": "getActivityButtonPressMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}, {"$ref": "#/components/parameters/button_press"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EntityCommand"}, "examples": {"default": {"value": {"cmd_id": "HOME"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Remove a button press mapping.", "operationId": "deleteActivityButtonPressMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}, {"$ref": "#/components/parameters/button_press"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/activities/{entityId}/ui": {"get": {"tags": ["activities"], "summary": "Get the user interface definition of an activity.", "description": "Returns all the information required to manage an existing activity user interface.\n\nAt the moment a user interface only consists of pages.\n", "operationId": "getActivityUi", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterface"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Reset an activity user interface to its default state.", "description": "\u26a0\ufe0f The customization of the activity user interface is irrevocably deleted.\n", "operationId": "deleteActivityUi", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterface"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/activities/{entityId}/ui/pages": {"post": {"tags": ["activities"], "summary": "Create a new user interface page", "description": "Append a new empty page to the user interface pages. The new page identifier is returned in the response.\n\nThe payload fields are optional. A page name and the items of the page can be specified, or later be added with \n`PATCH /activities/{entityId}/ui/pages/{pageId}`. If `grid` is not specified, the default grid size is used from\nthe screen metadata layout in `GET /cfg/device/screen_layout`\n", "operationId": "createActivityUiPage", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePageUpdate"}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "object", "properties": {"page_id": {"$ref": "#/components/schemas/SimpleId"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["activities"], "summary": "Get the user interface pages of an activity.", "operationId": "getActivityUiPages", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["activities"], "summary": "Update the activity user interface page order.", "operationId": "updateActivityUiPageOrder", "description": "Reorder the pages in the user interface according to the page identifiers in the `page_order` array.\n", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"page_order": {"type": "array", "items": {"$ref": "#/components/schemas/SimpleId"}}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Reset the activity user interface pages to the default state.", "description": "The default page(s) is created and the page array returned.\n\n\u26a0\ufe0f The customization of the activity user interface is irrevocably deleted.\n", "operationId": "resetActivityUiPages", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/activities/{entityId}/ui/pages/{pageId}": {"get": {"tags": ["activities"], "summary": "Get the user interface page definition of an activity-entity.", "operationId": "getActivityUiPage", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/page_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["activities"], "summary": "Update an activity user interface page.", "operationId": "updateActivityUiPage", "description": "Update one or multiple properties of an activity user interface page. The omitted properties are ignored and not\ndeleted. To clear an array simply provide an empty array.\n", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/page_id"}], "requestBody": {"description": "Properties to update in the existing activity user interface page.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePageUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Delete an activity user interface page.", "description": "The given page is removed and the array of remaining pages is returned.\n\n\u26a0\ufe0f The customization of the activity user interface page is irrevocably deleted.\n", "operationId": "deleteActivityUiPage", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/page_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/activity_groups": {"head": {"tags": ["activities"], "summary": "Get total number of activity groups.", "description": "The total number of activity groups is returned in the `Pagination-Count` header. This allows to prepare the\nretrieval of the groups with the `GET` operation and paging parameters.\n", "operationId": "getActivityGroupCount", "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["activities"], "summary": "Get activity groups overview with paging.", "description": "Returns an overview of all defined activity groups with the given paging parameters. Use the `HEAD` operation to\nretrieve the total number of defined groups.\n\nThe overview information doesn't include all details of an activity group. The full group information is\nretrievable with `/activity_group/{groupId}`.\n", "operationId": "getActivityGroups", "parameters": [{"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityGroups"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "post": {"tags": ["activities"], "summary": "Create a new activity group.", "description": "Create a new activity group.\n", "operationId": "createActivityGroup", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityGroupUpdate"}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityGroup"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["activities"], "summary": "Delete all activity groups.", "description": "\u26a0\ufe0f All defined activity groups except the default group will be irrevocably deleted!\n", "operationId": "deleteAllActivityGroups", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/activity_groups/{groupId}": {"get": {"tags": ["activities"], "summary": "Get an activity group by its group_id.", "description": "Returns all the information required to manage an existing activity group.\n", "operationId": "getActivityGroup", "parameters": [{"$ref": "#/components/parameters/group_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityGroup"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["activities"], "summary": "Update an activity group.", "operationId": "updateActivityGroup", "description": "Update one or multiple properties of an activity group. The omitted properties are ignored and not deleted.\n", "parameters": [{"$ref": "#/components/parameters/group_id"}], "requestBody": {"description": "Properties to update in the existing activity group.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityGroupUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityGroup"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["activities"], "summary": "Delete an activity group.", "description": "\u26a0\ufe0f The given activity group is irrevocably deleted.\n\nThe default activity group cannot be deleted and will return a `409` conflict error (requires Core version 0.64\nor newer).\n", "operationId": "deleteActivityGroup", "parameters": [{"$ref": "#/components/parameters/group_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}}}}, "/macros": {"head": {"tags": ["macros"], "summary": "Get total number of macro entities.", "description": "The total number of available macros are returned in the `Pagination-Count` header. This allows to prepare the\nretrieval of the macros with the `GET` operation and paging parameters.\n", "operationId": "getMacroCount", "parameters": [{"$ref": "#/components/parameters/query"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["macros"], "summary": "Get macro entities overview with paging.", "description": "Returns an overview of all defined macros with the given paging parameters. Use the `HEAD` operation to retrieve\nthe total number of defined macros.\n\nThe overview information doesn't include all details of a macro. The full macro information is retrievable\nwith `/macros/{entityId}`.\n\nThe optional text search query searches in the macro name and macro identifier.\n", "operationId": "getMacros", "parameters": [{"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}, {"$ref": "#/components/parameters/query"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Macros"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["macros"], "summary": "Create a new macro entity.", "description": "Create a new entity of type `macro`. An macro entity is a special internal entity without association to an\nintegration driver.\n\nTo create a new macro at least a name must be provided. The `icon`, `description` and `options.entity_ids`\nare optional and can be set later with the `PATCH` update operation.\n\nWhen setting a text in a multilingual field, like name or description, the default `en` identifier should always be\nincluded.\n\nThe new macro can be cloned from another macro-entity identifier in `clone_from`. All applicable configuration will\nbe copied, except a new macro name must be specified. The `icon` and `description` fields can still be specified and\nwill override the copied data. The `options.entity_ids` is not allowed when cloning data, additional entities\ncan be added later with the `PATCH` update operation.\n\nThe `entity_ids` may be omitted when creating a new macro and specified later when updating the macro.\n", "operationId": "createMacro", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/MacroCreate"}, "examples": {"simple": {"value": {"name": {"en": "My new macro"}}}, "macro with icon and description": {"value": {"name": {"en": "My new macro"}, "icon": "uc:bell", "description": {"en": "Testing the macro feature"}}}, "clone": {"value": {"name": {"en": "My cloned macro"}, "clone_from": "uc.main.macro.vacation-mode"}}}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Macro"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["macros"], "summary": "Delete all macro entities.", "description": "\u26a0\ufe0f All defined macros will be irrevocably deleted!\n", "operationId": "deleteAllMacros", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/macros/{entityId}": {"get": {"tags": ["macros"], "summary": "Get a macro by its entity_id.", "description": "Returns all the information required to manage an existing macro. The included entities are enriched with `name`,\n`icon`, `entity_type`, available commands and if the entity is still available or has been removed since the\nmacro was defined.\n", "operationId": "getMacro", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Macro"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["macros"], "summary": "Update a macro entity.", "operationId": "updateMacro", "description": "Update one or multiple properties of a macro. The omitted properties are ignored and not deleted. To clear an\narray simply provide an empty array.\n", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"description": "Properties to update in the existing macro.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MacroUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Macro"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["macros"], "summary": "Delete a macro entity.", "description": "\u26a0\ufe0f The given macro is irrevocably deleted.\n", "operationId": "deleteMacro", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/ir/codes/manufacturers": {"get": {"tags": ["infrared"], "summary": "Search supported infrared device manufacturers.", "description": "Device manufacturer search. The returned manufacturer identification will be used for the manufacturer specific IR\ncode set search with `GET /ir/codes/manufacturers/{manufacturerId}`.\n", "operationId": "searchIrDeviceManufacturers", "parameters": [{"name": "q", "in": "query", "description": "Manufacturer name query", "required": true, "schema": {"type": "string", "minLength": 2}, "examples": {"default": {"value": "Lucky Goldstar"}}}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "array", "items": {"type": "object", "properties": {"id": {"description": "Manufacturer identification", "type": "string"}, "name": {"description": "Manufacturer name", "type": "string"}, "custom": {"description": "Flag indicating if this manufacturer was created by the user", "type": "boolean"}}, "required": ["id", "name"]}}, "examples": {"default": {"value": [{"id": "lg", "name": "LG"}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/ir/codes/manufacturers/{manufacturerId}": {"get": {"tags": ["infrared"], "summary": "Search for infrared device code sets by manufacturer to create a remote entity.", "description": "Searching without the optional device query will only return the generic manufacturer IR code sets.\n", "operationId": "searchInfraredDevice", "parameters": [{"name": "manufacturerId", "in": "path", "description": "Manufacturer identification from search", "required": true, "schema": {"type": "string"}}, {"name": "q", "in": "query", "description": "Device name query for fulltext search. At least two characters are required.", "required": false, "schema": {"type": "string", "minLength": 2}}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "array", "items": {"type": "object", "properties": {"id": {"description": "Code set identifier", "type": "string"}, "name": {"description": "Device name", "type": "string"}, "custom": {"description": "Flag indicating if this manufacturer was created by the user", "type": "boolean"}}, "required": ["id", "name"]}}, "examples": {"default": {"value": [{"id": "1", "name": "Generic TV 1", "custom": false}, {"id": "2", "name": "Generic TV 2", "custom": false}, {"id": "3", "name": "Generic TV 3", "custom": false}, {"id": "4", "name": "Generic Projector", "custom": false}, {"id": "5", "name": "My BluRay Player", "custom": true}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/ir/codes/manufacturers/{manufacturerId}/{codeSetId}": {"get": {"tags": ["infrared"], "summary": "Retrieve IR codeset command information for testing IR commands.", "description": "Returns all command identifiers of a given manufacturer code set.\n", "operationId": "getManufacturerCodeSet", "parameters": [{"name": "manufacturerId", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "string"}}, "examples": {"default": {"value": ["POWER_ON", "POWER_OFF", "POWER_TOGGLE", "VOLUME_UP", "VOLUME_DOWN", "MUTE", "CHANNEL_UP", "CHANNEL_DOWN", "DPAD_LEFT", "DPAD_RIGHT", "DPAD_UP", "DPAD_DOWN", "ENTER", "OSD", "SETUP", "NUMPAD_0", "NUMPAD_1", "NUMPAD_2", "NUMPAD_3", "NUMPAD_4", "NUMPAD_5", "NUMPAD_6", "NUMPAD_7", "NUMPAD_8", "NUMPAD_9", "HDMI_1", "HDMI_2", "HDMI_3", "HDMI_4"]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/ir/codes/custom": {"head": {"tags": ["infrared"], "summary": "Get total number of custom infrared code sets.", "operationId": "getCustomIrDeviceCount", "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["infrared"], "summary": "Get all custom infrared code sets or export as CSV.", "description": "Depending on the `Content-Type` header, the custom infrared code sets are either returned as JSON objects\nor exported as a CSV file.\n\n- `Content-Type: application/json` or none: retrieve all custom infrared code set with paging.  \n  Use `GET /ir/codes/custom/{codeSetId}` to access the IR code definitions of a codeset.\n\n- `Content-Type: text/csv`: retrieve all custom codes as CSV export (without paging).  \n  Query parameters `page` and `limit` are ignored.\n", "operationId": "getCustomIrDeviceCodes", "parameters": [{"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}, {"name": "delimiter", "in": "query", "description": "CSV delimiter character. Only for CSV export.", "schema": {"type": "string", "default": ",", "minLength": 1, "maxLength": 1}}], "responses": {"200": {"description": "Successful operation, either with paginated JSON or CSV response.", "headers": {"Pagination-Count": {"description": "Total number of code sets.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items. Only for json response.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based. Only for json response.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/CodeSetInfo"}}}, "text/csv": {"schema": {"type": "string"}, "examples": {"default": {"value": "manufacturer,device,key,format,code\ncustom,My AVR,CURSOR_DOWN,HEX,3;0x20F0827D;32;0\ncustom,My AVR,CURSER_ENTER,HEX,3;0x20F022DD;32;0\ncustom,My AVR,CURSOR_LEFT,HEX,3;0x20F0E01F;32;0\ncustom,My AVR,CURSOR_RIGHT,HEX,3;0x20F0609F;32;0\ncustom,My AVR,CURSOR_UP,HEX,3;0x20F002FD;32;0\nFoobar,TV,POWER_ON,PRONTO,0000 006d 0000 0024 0157 00ac 0015 0015 0015 0015 0015 0040 0015 0015 0015 0015 0015 0015 0015 0015 0015 0015 0015 0040 0015 0040 0015 0015 0015 0040 0015 0040 0015 0040 0015 0040 0015 0040 0015 0015 0015 0015 0015 0040 0015 0015 0015 0015 0015 0015 0015 0040 0015 0040 0015 0040 0015 0040 0015 0015 0015 0040 0015 0040 0015 0040 0015 0015 0015 0015 0015 0689 0157 0056 0015 0e94\nFoobar,TV,POWER_OFF,PRONTO,0000 006d 0000 0024 0157 00ab 0015 0015 0016 0015 0016 003f 0016 0015 0015 0016 0015 0015 0016 0015 0016 0015 0015 0040 0015 0040 0015 0015 0016 003f 0016 003f 0016 003f 0016 003f 0016 003f 0016 003f 0016 0015 0016 003f 0016 0015 0015 0015 0016 0015 0016 003f 0016 003f 0016 0015 0015 0040 0015 0015 0016 003f 0016 003f 0016 003f 0016 0015 0016 0015 0015 05fd 0156 0055 0016 0ee1\n"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["infrared"], "summary": "Create a new custom infrared code set.", "description": "Create a new custom codeset for an IR device. The IR codes can already be provided or added later with\n`GET /ir/codes/custom/{codeSetId}/{key}`.\n\nIf the manufacturer isn't provided, the codeset will be linked to the custom manufacturer entry for self learned\ncodes.\n", "operationId": "createCustomIrDevice", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CodeSetCreate"}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CodeSetInfo"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["infrared"], "summary": "Delete all custom infrared code sets.", "description": "\u26a0\ufe0f All defined custom infrared device codes will be irrevocably deleted!\n", "operationId": "deleteAllCustomIrDeviceCodes", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/ir/codes/custom/{codeSetId}": {"get": {"tags": ["infrared"], "summary": "Get custom infrared code set or export as CSV.", "description": "Depending on the `Content-Type` header, the full definition of a custom infrared code set including the IR codes is\nreturned as JSON or exported as a CSV file.\n\n- `Content-Type: application/json` or none: retrieve infrared code set as JSON.\n- `Content-Type: text/csv`: export codeset as CSV.\n", "operationId": "getCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "delimiter", "in": "query", "description": "CSV delimiter character. Only for CSV export.", "schema": {"type": "string", "default": ",", "minLength": 1, "maxLength": 1}}], "responses": {"200": {"description": "Successful operation, either with paginated JSON or CSV response.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items. Only for json response.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based. Only for json response.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CodeSet"}}, "text/csv": {"schema": {"type": "string"}, "examples": {"default": {"value": "key,format,code\nCURSOR_DOWN,HEX,3;0x20F0827D;32;0\nCURSER_ENTER,HEX,3;0x20F022DD;32;0\nCURSOR_LEFT,HEX,3;0x20F0E01F;32;0\nCURSOR_RIGHT,HEX,3;0x20F0609F;32;0\nCURSOR_UP,HEX,3;0x20F002FD;32;0\n"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["infrared"], "summary": "Modify a custom infrared code set.", "description": "Rename the device or change the device type of an infrared code set.\n\nA device name must be unique and only custom infrared code sets can be modified.\n", "operationId": "updateCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CodeSetUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CodeSetInfo"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "post": {"tags": ["infrared"], "summary": "Bulk upload infrared codes with a CSV file.", "description": "Upload multiple IR codes from a CSV file into an existing code set.\n\nCSV file format:\n- delimiter character is `,` (comma). This can be overwritten with the query parameter `delimiter`.\n- character set: plain ASCII or UTF-8.\n- the first line must contain a header row.\n- required header columns:\n  - `key`: Key / button of the IR code.\n    - Valid character RegEx: `^[a-zA-Z0-9\\-_\\.]{1,50}$`\n    - Invalid characters will be replaced with an underscore.\n  - `code`: IR code\n  - \u26a0\ufe0f`key` and `code` must be lower-case, otherwise a validation error will be returned.\n- optional header column:\n  - `format`: IR code format: `PRONTO` or `HEX`. Default if missing: `PRONTO`\n- order of the header columns is not relevant, additional columns will be ignored.\n- rows with an empty `key` or `code` value are ignored.\n- duplicate `key` values are not allowed.\n  - The optional `overwrite` query parameter applies to existing keys only.\n- max size: 10 MB\n\nMinimal example:\n```csv\nkey,code\nPOWER_ON,0000 006d 0000 0020 000a\nPOWER_OFF,0000 006d 0000 0020 000b\n```\n\nNotes:    \n- If multiple files are specified in the form-data, only the first one will be processed.\n- Header and values are automatically trimmed from leading and trailing whitespace.\n- \u26a0\ufe0f In case there's an invalid record in the CSV file, all previous valid records will be added to the data set.\n", "operationId": "uploadCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "overwrite", "in": "query", "description": "Overwrite existing IR codes with the same key. Otherwise only new codes are added.", "schema": {"type": "boolean", "default": false}}, {"name": "delimiter", "in": "query", "description": "CSV delimiter character", "schema": {"type": "string", "default": ",", "minLength": 1, "maxLength": 1}}, {"name": "comment", "in": "query", "description": "The comment character at the start of a line to use when parsing CSV. No comment character is set by default.\n", "schema": {"type": "string", "minLength": 1, "maxLength": 1}}], "requestBody": {"content": {"multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"description": "IR code file to upload. File ending must be `.csv`.", "type": "string", "format": "binary"}}}}}, "required": true}, "responses": {"200": {"description": "Successful CSV import", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CodeSetUploadResult"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["infrared"], "summary": "Delete custom infrared code set.", "description": "\u26a0\ufe0f All defined custom infrared device codes will be irrevocably deleted!\n", "operationId": "deleteCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/ir/codes/custom/{codeSetId}/{key}": {"get": {"tags": ["infrared"], "summary": "Get a code definition from a custom infrared code set.", "description": "Retrieve the code definition for the given key in the infrared code set.\n", "operationId": "getCodeInCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/ir_key"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrCode"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["infrared"], "summary": "Add a new key to a custom infrared code set.", "description": "Enhance the infrared code set with a new key. The key must be unique in a given code set. Only custom code sets can\nbe modified.\n", "operationId": "addKeyInCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/ir_key"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrCodeUpdate"}}}, "required": true}, "responses": {"201": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "put": {"tags": ["infrared"], "summary": "Modify a code in a custom infrared code set.", "description": "Update the code definition of a key in an infrared code set. Only custom code sets can be modified.\n", "operationId": "updateCodeInCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/ir_key"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrCodeUpdate"}}}, "required": true}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["infrared"], "summary": "Delete an entry in a custom infrared code set.", "description": "\u26a0\ufe0f The key in the custom infrared device code set will be irrevocably deleted!\n", "operationId": "deleteKeyInCustomIrDeviceCodeSet", "parameters": [{"name": "codeSetId", "in": "path", "required": true, "schema": {"type": "string"}}, {"$ref": "#/components/parameters/ir_key"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/ir/convert/{format}": {"get": {"tags": ["infrared"], "summary": "Convert an IR code into a different format.", "description": "This GET endpoint to convert IR codes is intended for simple scripts and tests.\n\nParameters:\n- `code`: URL encoded PRONTO code or HEX Code (spaces, commas and semicolons must be encoded).\n- `repeat`: How many times to decode the repeat part of the IR code.\n  - Only relevant for IR formats not containing a repeat count, as: PRONTO\n  - PRONTO codes: repeats the data in the repeat sequence of the code.\n    - If the 4th field of the PRONTO code is `0000`, then it doesn't contain a repeat sequence and the repeat\n      parameter is ignored!\n    - If the code only contains a repeat sequence and a missing first sequence (3rd field is `0000`), the repeat\n      sequence is encoded at least once and the repeat count automatically increased by one.\n- `to`: The destination format. Only RAW IR timings are supported at the moment.\n", "operationId": "convertIrCode", "parameters": [{"name": "format", "in": "path", "description": "IR format", "required": true, "schema": {"$ref": "#/components/schemas/IrCodeFormat"}}, {"name": "code", "in": "query", "description": "IR code", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "repeat", "in": "query", "description": "Repeat count for PRONTO code", "required": false, "schema": {"type": "integer", "minimum": 0, "maximum": 20}}, {"name": "to", "in": "query", "description": "Destination IR format", "required": false, "schema": {"type": "string", "enum": ["RAW"]}}], "responses": {"200": {"description": "Successful IR code conversion", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrRawCode"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/ir/emitters": {"head": {"tags": ["infrared"], "summary": "Get total number of infrared emitter devices.", "operationId": "getInfraredEmitterCount", "parameters": [{"$ref": "#/components/parameters/active"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["infrared"], "summary": "Get all infrared emitter devices for sending IR codes.", "operationId": "getInfraredEmitters", "parameters": [{"$ref": "#/components/parameters/active"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrEmitters"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/ir/emitters/{emitterId}": {"get": {"tags": ["infrared"], "summary": "Get an IR emitter device.", "operationId": "getIrEmitter", "parameters": [{"$ref": "#/components/parameters/emitter_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrEmitter"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/ir/emitters/{emitterId}/send": {"put": {"tags": ["infrared"], "summary": "Send IR command.", "description": "Send an IR command from the specified command set or a learned / custom code on the given emitter and output port.\n\n### Continuous IR repeat\nIf supported by the emitter, this feature allows to repeat an IR signal autonomously by the emitting device for\na specified number of times.\n\n\u26a0\ufe0f Supported on the UnfoldedCircle Dock with firmware version 0.9.0 or newer. \n\nThe repeated IR signal is usually a special IR command to tell the receiving device, that a button on a remote\ncontrol is hold for a longer time. Depending on the device, a repeat signal can either simply execute the same\naction as if someone would rapidly press the same button, or it can adjust the command to a different function.\nOne common example is to progressively increase the volume steps, e.g. start slowly with 0.1 dBA steps, then\nafter a short time increase to 0.5 or 1 dBA steps.  \nPlease note that not all devices or IR formats / commands support this feature. This is manufacturer specific.\n\nThe continuous IR repeat feature is activated with the optional `repeat` field in the request.\n- The IR repeat signal will automatically be sent the number of times specified in the repeat field.\n- If the next request contains the same IR command, the repeat count will be reset in the dock and therefore\n  the repeat signal prolonged.\n- A 'PUT /ir/emitters/{emitterId}/stop_send' request will stop the remaining repeat commands.\n- Depending on the IR `format`, a repeat value might be already part of the `code`.\n  - \u26a0\ufe0f The `repeat` value will override the embedded repeat information.\n  - See _IR formats_ below.\n\nIf `repeat` is not specified (or set to zero):\n- The stored IR code in the `codeset_id` or provided `code` is sent as is, with the contained repeat information\n  (depending on IR format).\n- Continuous IR repeat is not activated:\n  - every IR send request will send the full IR command.\n  - \u26a0\ufe0f the 'PUT /ir/emitters/{emitterId}/stop_send' command will have no effect!\n\n### IR formats\n- `PRONTO`: PRONTO HEX format:\n  - Only raw codes are supported (first number is `0000`).\n  - The PRONTO HEX format does not include a dedicated repeat count field, but an optional 2nd burst\n    pair sequence used for repeats.\n    - The third number in the PRONTO code specifies the number of burst pairs in the 1st sequence.\n    - The fourth number in the PRONTO code specifies the number of burst pairs in the 2nd sequence.\n    - If the fourth number is 0, then there's no repeat sequence.\n    - Note that either sequence is optional. Also there might be both sequences defined, or only the\n      1st or 2nd one.\n  - If the `repeat` field is set (> 0), the 2nd burst pair sequence of the PRONTO code is repeated.\n    - If the PRONTO code doesn't contain a 2nd burst pair sequence, then the repeat value is ignored.\n- `HEX`: Unfolded Circle format:\n  - The repeat count is part of the code and might be required for certain protocols.\n    - E.g. Sony needs to send the same command two or three times so it's recognized as a single\n      command by a device.\n  - If the `repeat` field is set (> 0), this will override the repeat count in `code` (and not multiply the total\n    repeat count)!\n  - The actual emitted IR repeat signal depends on the IR protocols.\n    - E.g. Denon will simply repeat the full command, whereas LG has a mandatory repeat-specific code\n      sent after the command. This is all handled by the dock, when sending the IR code.\n", "operationId": "sendCommandOnEmitter", "parameters": [{"$ref": "#/components/parameters/emitter_id"}], "requestBody": {"description": "IR command", "content": {"application/json": {"schema": {"oneOf": [{"type": "object", "description": "Command from a codeset.", "properties": {"codeset_id": {"description": "Infrared codeset identifier.", "type": "string"}, "cmd_id": {"description": "Command identifier in the codeset.", "type": "string"}, "repeat": {"description": "Optional repeat value for sending continuous IR repeat signals (depending on IR protocol).\n", "type": "integer", "minimum": 0, "maximum": 20}, "cmd_delay": {"description": "Optional delay between sending IR commands, if `cmd_id` refers to a command with multiple IR codes.\n", "type": "integer", "minimum": 0}, "port_id": {"description": "Optional output port identifier. The default output will be used if omitted.", "type": "string"}}, "required": ["codeset_id", "cmd_id"]}, {"type": "object", "description": "IR code.", "properties": {"code": {"description": "IR code to send.\n- PRONTO codes can use a space or comma as separator.\n- Multiple codes can be separated by a plus `+` (for example: `0000 0068 0001 0000 0001 + 0000 0068 0001 0000 0002`).\n", "type": "string"}, "format": {"$ref": "#/components/schemas/IrCodeFormat"}, "repeat": {"description": "Optional repeat value for sending continuous IR repeat signals (depending on IR protocol).\n", "type": "integer", "minimum": 0, "maximum": 20}, "cmd_delay": {"description": "Optional delay between sending commands if `code` contains more than one IR command.\n", "type": "integer", "minimum": 0}, "port_id": {"description": "Optional output port identifier. The default output will be used if omitted.", "type": "string"}}, "required": ["code", "format"]}]}, "examples": {"Command from a codeset on default output": {"value": {"codeset_id": "ir.manufacturer.123", "cmd_id": "CHANNEL_DOWN"}}, "Command from a codeset on default output and repeat count": {"value": {"codeset_id": "ir.manufacturer.123", "cmd_id": "VOLUME_DOWN", "repeat": 4}}, "Command from a codeset on specific output": {"value": {"codeset_id": "ir.manufacturer.123", "cmd_id": "CHANNEL_DOWN", "port_id": "4"}}, "PRONTO code on default output": {"value": {"code": "0000,0068,0000,0010,0060,0018,0030,0018,0018,0018,0030,0018,0018,0018,0018,0018,0030,0018,0018,0018,0030,0018,0030,0018,0030,0018,0018,0018,0030,0018,0018,0018,0018,0018,0030,0318", "format": "PRONTO"}}, "PRONTO code on default output and repeat count": {"value": {"code": "0000 0068 0000 0010 0060 0018 0030 0018 0018 0018 0030 0018 0018 0018 0018 0018 0030 0018 0018 0018 0030 0018 0030 0018 0030 0018 0018 0018 0030 0018 0018 0018 0018 0018 0030 0318", "format": "PRONTO", "repeat": 4}}, "Learned HEX code on specific output": {"value": {"code": "3;0x20F0A956;32;0", "format": "HEX", "port_id": "4"}}}}}}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/ir/emitters/{emitterId}/stop_send": {"put": {"tags": ["infrared"], "summary": "Stop sending an IR command.", "description": "Stop an active IR repeat transmission.\n", "operationId": "stopSendOnEmitter", "parameters": [{"$ref": "#/components/parameters/emitter_id"}], "requestBody": {"description": "IR stop command", "content": {"application/json": {"schema": {"type": "object", "properties": {"port_id": {"description": "Optional output port identifier. Requires support by IR emitter device.\nNot supported by Unfolded Circle dock\n", "type": "string"}}}}}}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/ir/emitters/{emitterId}/learn": {"get": {"tags": ["infrared"], "summary": "Get IR learning status and results.", "description": "Returns the current status and if the dock is in IR learning mode. All learned codes will be returned since the\nstart of the learning session.\n", "operationId": "irLearningStatusEmitter", "parameters": [{"$ref": "#/components/parameters/emitter_id"}], "responses": {"200": {"description": "IR learning status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrEmitterLearnStatus"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["infrared"], "summary": "Start IR learning.", "description": "Learn IR commands from the given emitter with learning capability. The learning session will be stopped\nautomatically after the timeout, unless it hasn't been stopped with the `DELETE` operation, or a new learning\nsession has been initiated.\n\nAny learned code will immediately be sent as a WebSocket `ir_learning`event message in the `emitters` channel.\nFurthermore, the codes are stored for retrieval with the `GET` status call. There's a maximum of 16 learned\ncodes per session. Any additional codes will be ignored and only sent as a WebSocket event.\n\nCalling this function, while learning is still active, will extend the timeout. Any previously learned codes\nwill not be deleted.\n", "operationId": "startIrLearningEmitter", "parameters": [{"$ref": "#/components/parameters/emitter_id"}, {"name": "timeout", "in": "query", "description": "Timeout in seconds.", "required": false, "schema": {"type": "integer", "format": "int32", "default": 60, "minimum": 1, "maximum": 300}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["infrared"], "summary": "Stop IR learning and clear results.", "description": "The current status and any learned codes will be returned. After this call the learned codes are no longer\naccessible through the `GET` status call.\n", "operationId": "stopIrLearningEmitter", "parameters": [{"$ref": "#/components/parameters/emitter_id"}], "responses": {"200": {"description": "IR learning status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IrEmitterLearnStatus"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes": {"head": {"tags": ["remotes"], "summary": "Get total number of remote-entities.", "description": "The total number of available remotes of the specified kind (BT, IR, external) are returned in the\n`Pagination-Count` header. This allows to prepare the retrieval of the remotes with the `GET` operation\nand paging parameters.\n\nOnly the IR-entity count is returned if no remote-`kind` query parameter is specified.\n", "operationId": "getRemoteCount", "parameters": [{"name": "kind", "in": "query", "description": "Remote kind", "required": false, "schema": {"$ref": "#/components/schemas/RemoteKind"}}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["remotes"], "summary": "Get remote-entities overview with paging.", "description": "Returns an overview of all defined remotes of the specified kind (BT, IR, external) with the given paging\nparameters. Use the `HEAD` operation to retrieve the total number of defined remotes.\n\nThe overview information doesn't include all details of a remote. The full remote information is retrievable\nwith `/remotes/{entityId}`.\n\nOnly the IR-entity count is returned if no remote-`kind` query parameter is specified.\n", "operationId": "getRemotes", "parameters": [{"name": "kind", "in": "query", "description": "Remote kind", "required": false, "schema": {"$ref": "#/components/schemas/RemoteKind"}}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Remotes"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["remotes"], "summary": "Create a new BT- or IR-remote entity.", "description": "Create a new Bluetooth or infrared `remote`-entity. External remote-entities cannot be created, they must be\nprovided by integration drivers. BT- and IR-entities are special internal entities without an integration driver\nassociation.\nInfrared-remote entities can be created with a manufacturer IR code-set or an empty custom code-set to learn or load\ncustom IR codes. Bluetooth-remote entities emulate a HID keyboard and mouse. An optional device-profile can be\nspecified to customize the available commands and key-mappings.\n\nTo create a new remote at least a name must be provided. \nThe `icon` and `description` properties are optional and can be set later with the `PUT` update operation.\n\nWhen setting a text in a multilingual field, like name or description, the default `en` identifier should always be\nincluded.\n\nIR-remotes:\n- If no manufacturer infrared code set is specified in `options.codeset_id`, a new custom code set is automatically\n  created for the user to manually specify or learn the codes.\n\nBT-remotes:\n- Device profiles can be retrieved with the `GET /cfg/bt/profiles` endpoint.\n- Custom device profiles can be uploaded with the resource API endpoint `POST /resources/BtDeviceProfile`.\n- If no device-profile is specified, the default profile is used which exposes all HID key commands.\n\nThe new remote can be cloned from another remote-entity identifier in `clone_from`. All applicable configuration\nwill be copied, except a new remote name must be specified. The `icon` and `description` fields can still be\nspecified and will override the copied data. The `options.codeset_id` is not allowed when cloning an IR-remote.\n", "operationId": "createRemote", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/RemoteCreate"}, "examples": {"create IR-remote with existing code set": {"value": {"name": {"en": "My new remote"}, "codeset_id": "ir.manufacturer.123"}}, "create IR-remote with custom code set (default device type & manufacturer)": {"value": {"name": {"en": "My custom remote"}, "custom_codeset": {"device_name": "My device"}}}, "IR-remote with icon, description and custom code set": {"value": {"name": {"en": "My custom remote"}, "icon": "uc:movie", "description": {"en": "Testing the custom code set feature"}, "custom_codeset": {"manufacturer_id": "custom", "device_name": "My device", "device_type": "various"}}}, "create Bluetooth-remote": {"value": {"name": {"en": "My BT remote"}, "icon": "uc:tv", "description": {"en": "Using the default device profile"}, "kind": "BT", "bt": {"dev_profile_id": "generic_android"}}}, "clone": {"value": {"name": {"en": "My cloned remote"}, "clone_from": "uc.main.remote.my-other-remote"}}}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Remote"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "delete": {"tags": ["remotes"], "summary": "Delete all remote-entities.", "description": "\u26a0\ufe0f All defined entities will be irrevocably deleted!\n", "operationId": "deleteAllRemotes", "parameters": [{"name": "kind", "in": "query", "description": "Remote kind", "required": false, "schema": {"$ref": "#/components/schemas/RemoteKind"}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/remotes/{entityId}": {"get": {"tags": ["remotes"], "summary": "Get a remote-entity by its entity_id.", "description": "Returns all the information required to manage an existing remote.\n", "operationId": "getRemote", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Remote"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["remotes"], "summary": "Update a remote-entity.", "operationId": "updateRemote", "description": "Update one or multiple properties of a remote-entity. The omitted properties are ignored and not deleted.\nTo clear an array simply provide an empty array.\n\n- Button mappings are configured with the dedicated `/remotes/{entityId}/buttons` and\n  `/remotes/{entityId}/buttons/{button}` endpoints.\n- The user interface is configured with the dedicated `/remotes/{entityId}/ui`, `/remotes/{entityId}/ui/pages`\n  and `/remotes/{entityId}/ui/pages/{pageId}` endpoints.\n", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"description": "Properties to update in the existing remote-entity.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RemoteUpdate"}, "examples": {"Name, icon and description": {"value": {"name": {"en": "New remote name"}, "icon": "uc:tv", "description": {"en": "Updated description"}}}, "Output emitter": {"value": {"options": {"ir": {"output": {"device_id": "sim.1", "port_id": "4"}}}}}, "Infrared code set (NOT YET IMPLEMENTED)": {"value": {"options": {"ir": {"codeset": {"id": "lg3"}}}}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Remote"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Delete a remote-entity.", "description": "\u26a0\ufe0f The given entity is irrevocably deleted.\n", "operationId": "deleteRemote", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/ir": {"get": {"tags": ["remotes"], "summary": "Get the infrared dataset of the remote-entity.", "description": "Returns all the information required to manage the infrared dataset.\n", "operationId": "getRemoteIrDataSet", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RemoteIrDataSet"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/ir/{cmdId}": {"post": {"tags": ["remotes"], "summary": "Add a custom infrared command to the codeset.", "operationId": "addRemoteIrCode", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/cmd_id"}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"value": {"$ref": "#/components/schemas/IrCodeValue"}, "format": {"$ref": "#/components/schemas/IrCodeFormat"}}, "required": ["value", "format"]}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RemoteIrCode"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["remotes"], "summary": "Gets an infrared code in the codeset.", "description": "Returns the details of a given infrared command.\n", "operationId": "getRemoteIrCode", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"name": "cmdId", "in": "path", "description": "IR command identification.", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RemoteIrCode"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["remotes"], "summary": "Update an infrared command in the codeset.", "operationId": "updateRemoteIrCode", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"name": "cmdId", "in": "path", "description": "IR command identification.", "required": true, "schema": {"type": "string"}}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"value": {"$ref": "#/components/schemas/IrCodeValue"}, "format": {"$ref": "#/components/schemas/IrCodeFormat"}}, "required": ["value", "format"]}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RemoteIrCode"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Delete a custom ir code or reset a modified manufacturer code in the codeset.", "operationId": "deleteOrResetRemoteIrCode", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"name": "cmdId", "in": "path", "description": "IR command identification.", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/bt": {"get": {"tags": ["remotes"], "summary": "\ud83e\uddea Get information about a Bluetooth remote-entity.", "description": "Retrieve information of this BT-remote entity.\n\nResponse codes:\n- `400 Bad Request` is returned if the entity is not a BT-remote entity.\n", "operationId": "getBtRemoteInfo", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BtRemoteInfo"}, "examples": {"Newly created BT-remote entity": {"value": {"profile": 1, "dev_profile_id": "default", "peripherals": {"keyboard": true, "mouse": true}}}, "Paired BT-remote entity": {"value": {"profile": 1, "dev_profile_id": "my_device", "peer": {"address": "AE:35:DC:88:AA:11", "addr_type": "LE_PUBLIC"}, "peripherals": {"keyboard": true, "mouse": false}}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/bt/pairing": {"get": {"tags": ["remotes"], "summary": "\ud83e\uddea Get pairing information of a Bluetooth remote-entity.", "description": "Retrieve pairing specific information of this BT-remote entity.\n\n- If the peripheral is paired (`paired: true`), the peer address is returned in the `peer` field.\n- If there's a bonding request from a central, the `bonding_request` object is set.\n  - \u203c\ufe0f Only `PasskeyInput` bonding requests are currently supported.\n\nResponse codes:\n- `400 Bad Request` is returned if the entity is not a BT-remote entity.\n", "operationId": "getBtRemotePairingInfo", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BtRemotePairingInfo"}, "examples": {"Paired peripheral": {"value": {"paired": true, "pairing_enabled": true, "peer": {"address": "AE:35:DC:88:AA:11", "addr_type": "LE_PUBLIC"}}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["remotes"], "summary": "\ud83e\uddea Enable or disable BT-remote pairing.", "description": "Once a BT-remote entity is paired with a central, it will no longer accept pairing requests from a central.\nFor example if the user removed the pairing information (usually through a \"forget this Bluetooth device\" action).\n\nThis command enables pairing again. Note: there is no timeout, the peripheral remains in pairing mode as long as\nit is not deactivated again!\n\nThe current pairing state can be retrieved with `GET /remotes/{entityId}/bt/pairing`.\n\nResponse codes:\n- `400 Bad Request`: invalid request data or if the entity is not a BT-remote entity.\n- `503 Service Unavailable`: BT is switched off, or the service is not responding.\n", "operationId": "enableBtRemotePairing", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"name": "enabled", "in": "query", "description": "Enable pairing.", "required": true, "schema": {"type": "boolean", "default": true}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "post": {"tags": ["remotes"], "summary": "\ud83e\uddea Send a pairing response.", "description": "Send the displayed pairing passkey on the central or decline a pairing request.\n\nResponse codes:\n- `400 Bad Request`: invalid request data or if the entity is not a BT-remote entity.\n- `503 Service Unavailable`: BT is switched off, or the service is not responding.\n", "operationId": "sendPairingResponse", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BtPairingResponse"}, "examples": {"Passkey entry": {"value": {"id": 11, "passkey": "012345"}}, "Decline passkey pairing request": {"value": {"id": 11, "confirm": false}}, "Accept non-passkey pairing request": {"value": {"id": 12, "confirm": true}}}}}, "required": true}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/remotes/{entityId}/buttons": {"get": {"tags": ["remotes"], "summary": "Get the physical button mappings.", "operationId": "getRemoteButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}, "examples": {"default": {"value": [{"button": "DPAD_DOWN", "short_press": {"cmd_id": "CURSOR_DOWN"}, "long_press": {"cmd_id": "BACK"}}, {"button": "DPAD_MIDDLE", "short_press": {"cmd_id": "CURSOR_ENTER"}}, {"button": "DPAD_LEFT", "short_press": {"cmd_id": "CURSOR_LEFT"}}, {"button": "DPAD_RIGHT", "short_press": {"cmd_id": "CURSOR_RIGHT"}}, {"button": "DPAD_UP", "short_press": {"cmd_id": "CURSOR_UP"}}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["remotes"], "summary": "Merge multiple physical button mappings.", "description": "Update multiple button mappings at once. This merges the provided mappings with the existing mappings.\nIf a button object is provided it will be added to the mappings, or an existing mapping be updated.\nIf a short or long press entity command is missing in the update, the existing command will be kept.\n", "operationId": "mergeRemoteButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["remotes"], "summary": "Replace physical button mappings.", "description": "Replace all button mappings with the provided mappings.\n", "operationId": "updateRemoteButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Reset the physical button mappings to their default state.", "description": "An automatic mapping of common functions to the physical buttons is performed. This depends on the chosen IR codeset\nif e.g. the volume up & down keys are automatically mapped.\n\n\u26a0\ufe0f The previous customization of the physical button mapping is irrevocably deleted.\n", "operationId": "resetRemoteButtonMappings", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}, "examples": {"default": {"value": [{"button": "BACK", "short_press": {"cmd_id": "BACK"}}, {"button": "DPAD_DOWN", "short_press": {"cmd_id": "CURSOR_DOWN"}}, {"button": "DPAD_MIDDLE", "short_press": {"cmd_id": "CURSOR_ENTER"}}, {"button": "DPAD_LEFT", "short_press": {"cmd_id": "CURSOR_LEFT"}}, {"button": "DPAD_RIGHT", "short_press": {"cmd_id": "CURSOR_RIGHT"}}, {"button": "DPAD_UP", "short_press": {"cmd_id": "CURSOR_UP"}}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/buttons/{buttonId}": {"get": {"tags": ["remotes"], "summary": "Get a physical button mapping.", "operationId": "getRemoteButtonMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMapping"}, "examples": {"default": {"value": {"button": "DPAD_DOWN", "short_press": {"cmd_id": "HOME"}, "long_press": {"cmd_id": "MENU"}}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["remotes"], "summary": "Update a physical button mapping.", "description": "Update the button mapping for either a short- or a long-press.\n\n\u26a0\ufe0f In the EntityCommand object the `entity_id` may not be specified. A remote-entity always operates on its own\ncommands. If you want to control other entities, an activity must be used.\n", "operationId": "updateRemoteButtonMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}], "requestBody": {"content": {"application/json": {"schema": {"oneOf": [{"type": "object", "properties": {"short_press": {"$ref": "#/components/schemas/EntityCommand"}}, "required": ["short_press"]}, {"type": "object", "properties": {"long_press": {"$ref": "#/components/schemas/EntityCommand"}}, "required": ["long_press"]}]}, "examples": {"short button press": {"value": {"short_press": {"cmd_id": "HOME"}}}, "long button press": {"value": {"long_press": {"cmd_id": "MENU"}}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMapping"}, "examples": {"default": {"value": {"button": "DPAD_DOWN", "short_press": {"cmd_id": "HOME"}}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Remove a physical button mapping.", "description": "\u26a0\ufe0f The previous customization of the physical button mapping is irrevocably deleted.\n", "operationId": "deleteRemoteButtonMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DeviceButtonMappings"}, "examples": {"default": {"value": [{"button": "DPAD_MIDDLE", "short_press": {"cmd_id": "CURSOR_ENTER"}}, {"button": "DPAD_LEFT", "short_press": {"cmd_id": "CURSOR_LEFT"}}, {"button": "DPAD_RIGHT", "short_press": {"cmd_id": "CURSOR_RIGHT"}}, {"button": "DPAD_UP", "short_press": {"cmd_id": "CURSOR_UP"}}]}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/buttons/{buttonId}/{buttonPress}": {"get": {"tags": ["remotes"], "summary": "Get a button press mapping.", "operationId": "getRemoteButtonPressMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}, {"$ref": "#/components/parameters/button_press"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EntityCommand"}, "examples": {"default": {"value": {"cmd_id": "HOME"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Remove a button press mapping.", "operationId": "deleteRemoteButtonPressMapping", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/button_id"}, {"$ref": "#/components/parameters/button_press"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/ui": {"get": {"tags": ["remotes"], "summary": "Get the user interface definition of a remote-entity.", "description": "Returns all the information required to manage an existing remote user interface.\n\nAt the moment a user interface only consists of pages.\n", "operationId": "getRemoteUi", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterface"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Reset a remote user interface to its default state.", "description": "\u26a0\ufe0f The customization of the remote user interface is irrevocably deleted.\n", "operationId": "deleteRemoteUi", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterface"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/ui/pages": {"post": {"tags": ["remotes"], "summary": "Create a new user interface page", "description": "Append a new empty page to the user interface pages. The new page identifier is returned in the response.\n\nThe payload fields are optional. A page name and the items of the page can be specified, or later be added with \n`PATCH /remotes/{entityId}/ui/pages/{pageId}`. If `grid` is not specified, the default grid size is used from\nthe screen metadata layout in `GET /cfg/device/screen_layout`\n\n\u26a0\ufe0f If the user interface items with `command` objects are specified, then the `EntityCommand` structure may not\ncontain an `entity_id` field. A remote-entity always operates on itself.\n", "operationId": "createRemoteUiPage", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePageUpdate"}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "object", "properties": {"page_id": {"$ref": "#/components/schemas/SimpleId"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["remotes"], "summary": "Get the user interface pages of a remote-entity.", "operationId": "getRemoteUiPages", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["remotes"], "summary": "Update the remote user interface page order.", "operationId": "updateRemoteUiPageOrder", "description": "Reorder the pages in the user interface according to the page identifiers in the `page_order` array.\n", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"page_order": {"type": "array", "items": {"$ref": "#/components/schemas/SimpleId"}}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Reset the remote user interface pages to the default state.", "description": "The default page(s) is created and the page array returned.\n\n\u26a0\ufe0f The customization of the remote user interface is irrevocably deleted.\n", "operationId": "resetRemoteUiPages", "parameters": [{"$ref": "#/components/parameters/entity_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/remotes/{entityId}/ui/pages/{pageId}": {"get": {"tags": ["remotes"], "summary": "Get the user interface page definition of a remote-entity.", "operationId": "getRemoteUiPage", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/page_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["remotes"], "summary": "Update a remote user interface page.", "operationId": "updateRemoteUiPage", "description": "Update one or multiple properties of a remote user interface page. The omitted properties are ignored and not deleted.\nTo clear an array simply provide an empty array.\n", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/page_id"}], "requestBody": {"description": "Properties to update in the existing remote user interface page.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePageUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["remotes"], "summary": "Delete a remote user interface page.", "description": "The given page is removed and the array of remaining pages is returned.\n\n\u26a0\ufe0f The customization of the remote user interface page is irrevocably deleted.\n", "operationId": "deleteRemoteUiPage", "parameters": [{"$ref": "#/components/parameters/entity_id"}, {"$ref": "#/components/parameters/page_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/profiles": {"post": {"tags": ["profiles"], "summary": "Create a new profile.", "description": "There are two different types of profiles:\n\n- Normal profile (default): can do anything, change settings, add pages, entities, integrations, etc.\n- Restricted profile: intended for guests or children, who can only use the remote, but cannot change settings.\n\nThe admin PIN is required to switch from a restricted to a normal profile. It can be defined in settings.  \n\n- Switching away from a restricted profile will prompt the user to enter the admin PIN.\n- Switching to a restricted profile can be done without entering the admin PIN.\n\nProfile request object:    \n- `profile_id` is optional and auto-generated if not specified. Otherwise it needs to be a unique profile identifier.\n- `name` is mandatory and must be unique.\n- if the first profile is added, it is automatically set as the active profile.\n", "operationId": "createProfile", "requestBody": {"description": "Profile data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProfileRequest"}, "examples": {"Simple profile": {"value": {"name": "My profile"}}, "Profile with an icon": {"value": {"name": "My profile", "icon": "uc:star"}}, "Restricted profile": {"value": {"name": "Guests", "icon": "uc:lock", "restricted": true}}}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the profile identifier in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Profile"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "put": {"tags": ["profiles"], "summary": "Switch active profile.", "description": "The administrator PIN in `admin_pin` is required to switch from a restricted to a normal profile.\nIf the current profile is a restricted profile and the pin is missing, error `401` is returned.\n", "operationId": "switchProfile", "parameters": [{"name": "active_profile_id", "in": "query", "description": "Active profile identifier", "required": true, "schema": {"type": "string"}}], "requestBody": {"description": "Optional administrator pin", "content": {"application/json": {"schema": {"type": "object", "properties": {"admin_pin": {"$ref": "#/components/schemas/AdminPin"}}}}}, "required": false}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "get": {"tags": ["profiles"], "summary": "Get all profiles or the active profile.", "description": "If the active profile is requested and no profile exists, or set active, 404 is returned.\n", "operationId": "getProfiles", "parameters": [{"$ref": "#/components/parameters/active"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Profiles"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["profiles"], "summary": "Delete all profiles.", "operationId": "deleteAllProfiles", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/profiles/{profileId}": {"get": {"tags": ["profiles"], "summary": "Get profile.", "operationId": "getProfile", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Profile"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["profiles"], "summary": "Update properties of a profile.", "description": "Update one or multiple properties of a profile. A missing property will not update its current value.  \n- `profile_id` is mandatory and can't be changed.\n- an empty `icon` value removes an existing icon identifier.\n- a missing `pages` property will not change the page order.\n- \u26a0\ufe0f an empty `pages` array removes all pages and groups in the profile!\n- \u26a0\ufe0f missing page identifiers in the `pages` array will remove the page configuration!\n", "operationId": "updateProfile", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "requestBody": {"description": "Properties to update in the existing profile.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProfileUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Profile"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["profiles"], "summary": "Delete profile.", "operationId": "deleteProfile", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/profiles/{profileId}/pages": {"post": {"tags": ["profiles"], "summary": "Create a new page in the profile.", "operationId": "createPage", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "requestBody": {"description": "Profile data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PageCreate"}, "examples": {"Simple page": {"value": {"name": "My page"}}, "New page at the first position": {"value": {"name": "Favorites", "pos": 1}}, "New page with items": {"value": {"name": "My other page", "items": [{"entity_id": "switch1"}, {"entity_id": "mediaplayer1"}, {"entity_id": "blind1"}, {"group_id": "def:g2"}]}}}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the page identifier in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Page"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "get": {"tags": ["profiles"], "summary": "Get all pages of the profile.", "operationId": "getPagesInProfile", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Page"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["profiles"], "summary": "Delete all pages of the profile.", "operationId": "deleteAllPagesInProfile", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/profiles/{profileId}/pages/{pageId}": {"get": {"tags": ["profiles"], "summary": "Get a page of the profile", "operationId": "getPage", "parameters": [{"$ref": "#/components/parameters/profile_id"}, {"$ref": "#/components/parameters/page_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Page"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["profiles"], "summary": "Update properties of a page.", "operationId": "updatePage", "parameters": [{"$ref": "#/components/parameters/profile_id"}, {"$ref": "#/components/parameters/page_id"}], "requestBody": {"description": "Properties to update in the existing page.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PageUpdate"}, "examples": {"Rename page": {"value": {"name": "A better name"}}, "Rearrange items": {"value": {"items": [{"entity_id": "mediaplayer1"}, {"group_id": "def:g2"}, {"entity_id": "blind1"}, {"entity_id": "switch1"}]}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Page"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["profiles"], "summary": "Delete a page of the profile.", "operationId": "deletePage", "parameters": [{"$ref": "#/components/parameters/profile_id"}, {"$ref": "#/components/parameters/page_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/profiles/{profileId}/groups": {"post": {"tags": ["profiles"], "summary": "Create a new group in the profile.", "operationId": "createGroup", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "requestBody": {"description": "Profile data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GroupUpdate"}}}, "required": true}, "responses": {"201": {"description": "Successful operation returning the page identifier in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Group"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "get": {"tags": ["profiles"], "summary": "Get all groups of the profile.", "operationId": "getGroupsInProfile", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Groups"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["profiles"], "summary": "Delete all groups of the profile.", "operationId": "deleteAllGroupsInProfile", "parameters": [{"$ref": "#/components/parameters/profile_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/profiles/{profileId}/groups/{groupId}": {"get": {"tags": ["profiles"], "summary": "Get a group in the profile.", "operationId": "getGroup", "parameters": [{"$ref": "#/components/parameters/profile_id"}, {"$ref": "#/components/parameters/group_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Group"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["profiles"], "summary": "Update properties of a group.", "operationId": "updateGroup", "parameters": [{"$ref": "#/components/parameters/profile_id"}, {"$ref": "#/components/parameters/group_id"}], "requestBody": {"description": "Properties to update in the existing group.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GroupUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Group"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["profiles"], "summary": "Delete a group of the profile.", "operationId": "deleteGroup", "parameters": [{"$ref": "#/components/parameters/profile_id"}, {"$ref": "#/components/parameters/group_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/cfg": {"get": {"tags": ["cfg"], "summary": "Get all configuration settings.", "description": "Retrieve all system configuration settings at once. Updating a configuration setting must be performed with the\ncorresponding endpoint.\n", "operationId": "getAllSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgAll"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "delete": {"tags": ["cfg"], "summary": "Reset all settings to default values.", "description": "This resets all system configuration settings to factory defaults. Integration & profile settings are not affected.\n", "operationId": "resetAllSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgAll"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/bt": {"get": {"tags": ["cfg"], "summary": "\ud83e\uddea Get Bluetooth settings.", "description": "Retrieve Bluetooth settings\n\nAdvertisement name placeholders:\n- `000000` will be replaced with the last 3 BT MAC address values.\n- `00:00:00:00:00:00` will be replaced with the full BT MAC address.\n", "operationId": "getBtSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgBt"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "\ud83e\uddea Modify Bluetooth settings.", "description": "Change one or multiple Bluetooth settings. The remote must be restarted after a configuration change.\n\n- If `peripheral_connections` or `enable_hci_log` is not specified, the original setting will be kept.\n- The `peripheral_connections` setting must be enabled with a feature flag, otherwise it will be ignored and only\n  a single connection be used.\n", "operationId": "updateBtSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgBtUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgBt"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/bt/profiles": {"get": {"tags": ["cfg"], "summary": "Get Bluetooth device profiles.", "description": "Retrieve an overview of all available BT device profiles for BT-remote entities.\n\nPre-defined system profiles and custom profiles are returned. Custom profiles can override system profiles if they\nspecify the same `id`. The type of profile is indicated in the `user_profile` flag.\n", "operationId": "getBtDeviceProfiles", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BtDeviceProfileInfos"}, "examples": {"default": {"value": [{"id": "default", "name": {"en": "Default"}, "version": 1, "peripherals": {"keyboard": true, "mouse": true}}, {"id": "generic_android", "name": {"en": "Generic Android"}, "version": 1, "peripherals": {"keyboard": true, "mouse": true}}, {"id": "my_device", "name": {"en": "My custom device"}, "user_profile": true, "version": 2, "peripherals": {"keyboard": true, "mouse": false}}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/bt/profiles/{id}": {"get": {"tags": ["cfg"], "summary": "Retrieve a Bluetooth device profile.", "description": "Retrieve a specific BT device profile for BT-remote entities. System and custom profiles can be retrieved.\n\nTo upload and delete custom profiles, please use the resource endpoints: `/resources/BtDeviceProfile`.\n", "operationId": "getBtDeviceProfile", "parameters": [{"$ref": "#/components/parameters/resource_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BtDeviceProfile"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/cfg/button": {"get": {"tags": ["cfg"], "summary": "Get button settings.", "description": "Button backlight configuration.\n\nDevice features:\n- `BACKLIGHT`: buttons have backlight (UCR2, UCR3).  \n- `RGB_COLOR`: RGB color backlight support (UCR3).\n- `ZONES`: backlight can be controlled with individual zones (UCR3).\n\nBacklight zone definitions can be retrieved with `/cfg/device/button_layout`.\n\n\u26a0\ufe0f Individual color per zone is not yet supported.\n", "operationId": "getButtonSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgButtons"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify button settings.", "description": "Change one or multiple button backlight settings.\n", "operationId": "updateButtonSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgButtonsUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgButtons"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/device": {"get": {"tags": ["cfg"], "summary": "Get remote device settings.", "description": "The remote device settings contain the custom name of the remote.\n", "operationId": "getRemoteDeviceSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgRemoteDevice"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify remote device settings.", "description": "Change one or multiple remote device settings.\n", "operationId": "updateRemoteDeviceSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgRemoteDevice"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgRemoteDevice"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/device/button_layout": {"get": {"tags": ["cfg"], "summary": "Get the button layouts of the device.", "description": "Meta-information about the button groups, button layouts and backlight zone information.\n\nIf a button group supports backlight zones, an additional entry with button group `type` suffix `_backlight` is\ndefined.\n", "operationId": "getRemoteDeviceButtonLayoutSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/DeviceButtonLayout"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/device/icon_mapping": {"get": {"tags": ["cfg"], "summary": "Get the native icon mapping of the device.", "description": "Meta-information about the native icon mappings. These are the icon identifiers prefixed with `uc:`, e.g. `uc:cool`.\nThe remaining label is mapped to a unicode number in the icon font. For `uc:cool` the mapping will be: (`cool`, `\\uE91E`)\n\nNote: the example response omits the leading backslash to avoid character substitution in the browser!\n", "operationId": "getRemoteDeviceIconMapping", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"description": "Label -> Unicode map", "type": "object", "additionalProperties": {"type": "string"}}, "examples": {"default": {"value": {"cool": "uE91E", "heat": "uE91F", "home": "uE900"}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/device/screen_layout": {"get": {"tags": ["cfg"], "summary": "Get the screen layout of the device.", "description": "Meta-information about the screen grid size.\n", "operationId": "getRemoteDeviceScreenLayoutSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/DeviceScreenLayout"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/display": {"get": {"tags": ["cfg"], "summary": "Get display settings.", "description": "Display brightness and auto brightness configuration.\n", "operationId": "getDisplaySettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgDisplay"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify display settings.", "description": "Change one or multiple display settings.\n", "operationId": "updateDisplaySettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgDisplay"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgDisplay"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/entity/commands": {"get": {"tags": ["cfg"], "summary": "Get entity command definitions.", "description": "Meta-information about the entity commands.\n", "operationId": "getEntityCommandMetadata", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/EntityCommandMetadata"}}, "examples": {"default": {"value": [{"id": "button.press", "cmd_id": "press", "name": {"en": "Press", "de": "Bet\u00e4tigen"}}, {"id": "switch.on", "cmd_id": "on", "name": {"en": "On", "de": "Ein"}}, {"id": "switch.off", "cmd_id": "off", "name": {"en": "Off", "de": "Aus"}}, {"id": "switch.toggle", "cmd_id": "toggle", "name": {"en": "Toggle", "de": "Umschalten"}}, {"id": "light.on", "cmd_id": "on", "name": {"en": "Turn on", "de": "Einschalten"}}, {"id": "light.off", "cmd_id": "off", "name": {"en": "Turn off", "de": "Ausschalten"}}, {"id": "light.toggle", "cmd_id": "toggle", "name": {"en": "Toggle state", "de": "Umschalten"}}, {"id": "light.dim", "cmd_id": "on", "name": {"en": "Set brightness", "de": "Setze Helligkeit"}, "params": [{"name": {"en": "brightness", "de": "Helligkeit"}, "param": "brightness", "type": "number", "min": 0, "max": 100, "step": 1, "unit": "%"}]}, {"id": "light.color_temperature", "cmd_id": "on", "name": {"en": "Set color temperature", "de": "Setze Farbtemperatur"}, "params": [{"name": {"en": "Color temperature", "de": "Farbtemperatur"}, "param": "color_temperature", "type": "number", "min": 0, "max": 100, "step": 1, "unit": "%"}]}, {"id": "light.color", "cmd_id": "on", "name": {"en": "Set color", "de": "Setze Farbe"}, "params": [{"name": {"en": "Hue", "de": "Farbton"}, "param": "hue", "type": "number", "min": 0, "max": 360, "step": 1, "unit": "\u00b0"}, {"name": {"en": "saturation", "de": "Farbs\u00e4ttigung"}, "param": "saturation", "type": "number", "min": 0, "max": 100, "step": 1, "unit": "%"}]}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/features": {"get": {"tags": ["cfg"], "summary": "Get feature flag settings.", "description": "Feature flag configuration.\n", "operationId": "getFeatureFlagSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgFeatures"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify a feature flag.", "description": "Enable or disable a feature flag setting.\n", "operationId": "updateFeatureFlagSetting", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgFeatureUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgFeatures"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/haptic": {"get": {"tags": ["cfg"], "summary": "Get haptic settings.", "description": "Haptic configuration.\n", "operationId": "getHapticSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgHaptic"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify haptic settings.", "description": "Change one or multiple haptic settings.\n", "operationId": "updateHapticSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgHaptic"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgHaptic"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/localization": {"get": {"tags": ["cfg"], "summary": "Get localization settings.", "description": "Retrieve the language and region configuration.\n", "operationId": "getLocalizationSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgLocalization"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify localization settings.", "description": "Change one or multiple localization settings.\n", "operationId": "updateLocalizationSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgLocalization"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgLocalization"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/localization/tz_names": {"get": {"tags": ["cfg"], "summary": "Get all available time zone names.", "operationId": "getTimezoneNames", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "string"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/localization/countries": {"get": {"tags": ["cfg"], "summary": "Get all available countries.", "operationId": "getLocalizationCountries", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "object", "properties": {"code": {"$ref": "#/components/schemas/CountryCode"}, "name_en": {"description": "Country name in english. Native country names will be provided in additional `name_<language_code>`\nproperties.\n", "type": "string"}}, "additionalProperties": true, "required": ["code", "name_en"]}}, "examples": {"default": {"value": [{"code": "CH", "name_de": "Schweiz", "name_en": "Switzerland", "name_fr": "Suisse", "name_it": "Svizzera"}, {"code": "DE", "name_de": "Deutschland", "name_en": "Germany"}, {"code": "DK", "name_dk": "Danmark", "name_en": "Denmark"}, {"code": "HU", "name_en": "Hungary", "name_hu": "Magyarorsz\u00e1g"}, {"code": "NL", "name_en": "Netherlands", "name_nl": "Nederland"}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/localization/translations": {"get": {"tags": ["cfg"], "summary": "Get all available translations.", "description": "The available translations are provided from the UI application.  \nFuture UI versions might provide new or updated translations.\n", "operationId": "getTranslations", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "object", "properties": {"version": {"type": "string"}, "translations": {"type": "array", "items": {"type": "object", "properties": {"code": {"$ref": "#/components/schemas/LanguageCode"}, "name": {"type": "string"}}, "required": ["code", "name"]}}}, "required": ["version", "translations"]}, "examples": {"default": {"value": {"version": "default", "translations": [{"code": "da_DK", "name": "Dansk"}, {"code": "de_DE", "name": "Deutsch"}, {"code": "de_CH", "name": "Schwiizert\u00fc\u00fctsch"}, {"code": "fr_CH", "name": "Fran\u00e7ais (Suisse)"}, {"code": "it_CH", "name": "Italiano (Svizzera)"}, {"code": "hu_HU", "name": "Magyar"}, {"code": "nl_NL", "name": "Nederlands"}]}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/network": {"get": {"tags": ["cfg"], "summary": "Get network settings.", "description": "Retrieve network settings, as WiFi or Bluetooth status.\n\n\u26a0\ufe0f The `wake_on_wlan` field is deprecated, please use `wifi.wake_on_wlan` instead.\n", "operationId": "getNetworkSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetwork"}, "examples": {"Normal configuration": {"value": {"bt_enabled": true, "wifi_enabled": true, "wifi": {"wake_on_wlan": {"enabled": false}, "bands": ["a", "b"], "band": "auto", "ipv4_type": "DHCP"}, "bt": {"address": "AA:BB:CC:DD:EE:FF"}}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify network settings.", "description": "Change one or multiple network settings.\n\n\u26a0\ufe0f The `wake_on_wlan` field is deprecated, please use `wifi.wake_on_wlan` instead.\n- If `wake_on_wlan` is specified, it will also be stored in `wifi.wake_on_wlan`! \n\n\u26a0\ufe0f The `ws` configuration object is an expert setting intended for support issues. Those settings may not be\nexposed in a user frontend.\n- The `ws` object is only returned, after it has been set manually.\n- Settings stay persisted for PATCH requests not containing the `ws` key.\n- Return and apply current system settings: send a PATCH request with an empty object: `\"ws\": {}\".\n- The `ws` settings can be removed with a network configuration reset `DELETE /cfg/network` or through a full configuration reset: `DELETE /cfg`\n- Modifying any `ws` settings requires a system reboot.\n", "operationId": "updateNetworkSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetworkUpdate"}, "examples": {"Enable BT": {"value": {"bt_enabled": true}}, "Disable WiFi": {"value": {"wifi_enabled": false}}, "Enable WoWLAN": {"value": {"wifi": {"wake_on_wlan": {"enabled": true}}}}, "Enable expert settings": {"value": {"ws": {}}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetwork"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "delete": {"tags": ["cfg"], "summary": "Reset network settings.", "description": "Reset all network settings to their defaults.\n\nThe expert settings in the `ws` configuration object will be removed.\n", "operationId": "resetNetworkSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetwork"}, "examples": {"Default configuration": {"value": {"bt_enabled": false, "wifi_enabled": true, "wifi": {"bands": ["b"], "band": "auto", "ipv4_type": "DHCP"}}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/network/wifi": {"get": {"tags": ["cfg"], "summary": "Get advanced wifi network settings.", "description": "Retrieve advanced wifi specific settings like which frequency band (2.4 GHz or 5 GHz) to use.\n", "operationId": "getWifiNetworkSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetworkWifi"}, "examples": {"Auto configuration": {"value": {"bands": ["a", "b"], "band": "auto", "ipv4_type": "DHCP"}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify advanced wifi network settings.", "description": "Change one or multiple advanced wifi network settings.\n", "operationId": "updateWifiNetworkSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetworkWifiUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetworkWifi"}, "examples": {"Auto configuration": {"value": {"bands": ["a", "b"], "band": "auto", "ipv4_type": "DHCP"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "delete": {"tags": ["cfg"], "summary": "Reset advanced wifi network settings.", "description": "Reset all advanced network settings to their defaults.\n", "operationId": "resetWifiNetworkSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgNetworkWifi"}, "examples": {"Default configuration": {"value": {"bands": ["a", "b"], "band": "auto"}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/power_saving": {"get": {"tags": ["cfg"], "summary": "Get power settings.", "description": "Sleep timeout and wakeup sensitivity configuration.\n", "operationId": "getPowerSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgPowerSaving"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify power settings.", "description": "Change one or multiple power saving settings.\n", "operationId": "updatePowerSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgPowerSaving"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgPowerSaving"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/profile": {"get": {"tags": ["cfg"], "summary": "Get profile settings.", "operationId": "getProfileSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgProfile"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify profile settings.", "description": "Change profile administrator pin.\n\n- an empty `admin_pin` value will remove the pin.\n", "operationId": "updateProfileSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgProfileUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgProfile"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/software_update": {"get": {"tags": ["cfg"], "summary": "Get software update settings.", "description": "Software update configuration. See PATCH operation and data model description for more information.\n", "operationId": "getSoftwareUpdateSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgSoftwareUpdate"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify software update settings.", "description": "Change one or multiple software update settings.\n\nIf `check_for_updates` is enabled:\n- the device automatically checks for new updates daily. The check happens during a random time within the \n  OTA window time frame `ota_window_start` - `ota_window_end`.\n- if a new update is available, the update metadata is immediately downloaded and the firmware update file is\n  scheduled to download.\n- the firmware file will only download if the remote has at least 50% battery charge.\n- if the remote is not in the dock and suspended, the remote will not automatically wake up and the check\n  will be skipped.\n\nIf `auto_update` is enabled:\n- once the firmware file is downloaded it will be automatically installed in the next OTA check window.\n- the installation will only start if the remote has at least 50% battery charge.\n\nOTA window fields:\n- the stored values are used if omitted. \n- default values are set if not configured.\n- the time of day corresponds to the configured timezone.\n- for changing the update window, both start and end times are required, otherwise a default will be used.\n- if the end time is before the start time, the window will spawn over midnight, e.g. `23:00:00` - `01:00:00`.\n\nOptional software update channel & token:\n- the default release channel is used if not configured.\n- the stored values are used if omitted. \n- changing the update channel is intended for closed user groups only.  \n  \u26a0\ufe0f High chance of breaking changes, bugs and loosing data!\n- other channels than `default` might require an access token in `channel_token`.\n- \u26a0\ufe0f Changing the update channel or token requires a device restart, otherwise the automated updates will not use\n     the new channel!\n", "operationId": "updateSoftwareUpdateSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgSoftwareUpdate"}, "examples": {"default": {"value": {"check_for_updates": true, "auto_update": false, "ota_window_start": "02:15:00", "ota_window_end": "05:00:00"}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgSoftwareUpdate"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "delete": {"tags": ["cfg"], "summary": "Reset all software update settings to default values.", "description": "Set all software update settings to default values and use the default release update channel.\n", "operationId": "resetSoftwareUpdateSettings", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgSoftwareUpdate"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/sound": {"get": {"tags": ["cfg"], "summary": "Get sound settings.", "description": "Sound configuration.\n", "operationId": "getSoundSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgSound"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify sound settings.", "description": "Change one or multiple sound settings.\n", "operationId": "updateSoundSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgSound"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgSound"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/voice_control": {"get": {"tags": ["cfg"], "summary": "Get voice control settings.", "description": "Voice control configuration.\n", "operationId": "getVoiceControlSettings", "parameters": [{"name": "default", "in": "query", "description": "Get default values instead of configured values.", "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgVoiceControl"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "patch": {"tags": ["cfg"], "summary": "Modify voice control settings.", "description": "Change one or multiple voice control settings. A missing field will in the request object will keep the old value.\n\nIf the specified voice control entity does not exist, the voice assistant configuration will be removed.\n", "operationId": "updateVoiceControlSettings", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgVoiceControlUpdate"}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CfgVoiceControl"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/cfg/voice_control/voice_assistants": {"head": {"tags": ["cfg"], "summary": "Get total number of voice assistants.", "operationId": "getVoiceAssistantCount", "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["cfg"], "summary": "Get available voice assistants.", "parameters": [{"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "operationId": "getVoiceAssistants", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VoiceAssistants"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/docks": {"head": {"tags": ["dock"], "summary": "Get total number of configured docks.", "description": "By default only active docks are counted. This can be changed with the `active` query parameter.\n", "operationId": "getDockCount", "parameters": [{"$ref": "#/components/parameters/active"}], "responses": {"200": {"description": "Successful operation.", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "get": {"tags": ["dock"], "summary": "List configured docks and their connection state.", "description": "Returns all dock configuration with paging. The configuration data is enriched with current connection information.\nUse the `HEAD` operation to retrieve the total number of defined docking stations.\n\nBy default only active docks are returned. This can be changed with the `active` query parameter.\n", "operationId": "getDocks", "parameters": [{"$ref": "#/components/parameters/active"}, {"$ref": "#/components/parameters/page"}, {"$ref": "#/components/parameters/limit"}], "responses": {"200": {"description": "Successful operation", "headers": {"Pagination-Count": {"description": "Total number of items.", "schema": {"type": "integer"}}, "Pagination-Limit": {"description": "Number of returned items.", "schema": {"type": "integer"}}, "Pagination-Page": {"description": "Current page number. 1-based.", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockConfigurations"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["dock"], "summary": "Create a new dock configuration.", "description": "Manually create and persist a new dock configuration. This is a low-level operation without configuring and setting\nup the dock as with the `/docks/setup` endpoints! To establish a session to the dock, the connect operation must be\ncalled afterwards.  \n- Error `422` is returned if the given service name in `dock_id` already exists.\n- If `custom_ws_url` is not specified, the dock address is resolved through an mDNS service name lookup in `dock_id`.   \n- The `active` flag specifies if the dock will react to connection requests.\n- Non-active docks will not auto-connect and must be enabled first to be used.\n- Non-active docks won't be visible in the web-configurator.\n- If no `token` is provided the default token is used! The token is used to authenticate the WebSocket\n  connection once a connection to the dock is established. To change an existing token, use the \n  `PATCH /docks/devices/:dockId` operation.\n- If `model` is provided it must be one of the known dock model identifiers: `UCD2` or `YIO1DOCK`.\n", "operationId": "createDock", "requestBody": {"description": "Client information requesting access", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockConfigurationRequest"}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockConfiguration"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}}}, "put": {"tags": ["dock"], "summary": "Connect or disconnect all active dock connections.", "description": "Requests all active docks to establish or stop a session to the dock.  \nUse `GET /docks` or `GET /docks/devices/{dockId}` to check on the connection status.\n", "operationId": "executeCommandOnAllDocks", "parameters": [{"name": "cmd", "in": "query", "description": "Command to execute.", "required": true, "schema": {"type": "string", "enum": ["CONNECT", "DISCONNECT"]}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "delete": {"tags": ["dock"], "summary": "Delete all dock configurations.", "description": "\u26a0\ufe0f All defined dock configurations will be irrevocably deleted!\n\nActive dock sessions will be disconnected and the persisted dock configurations removed.\n", "operationId": "deleteAllDocks", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/docks/discover": {"get": {"tags": ["dock"], "summary": "Get docking station discovery status.", "description": "Returns the current discovery status and any discovered docks.\n\nUse the DELETE operation to stop an active discovery and PUT to start a new discovery.\n", "operationId": "getDockDiscoveryStatus", "responses": {"200": {"description": "Dock discovery status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockDiscoveryStatus"}, "examples": {"default": {"value": {"active": true, "docks": [{"id": "UC-Dock-E831CDD012A8", "configured": false, "friendly_name": "Living room", "address": "192.168.1.106:946", "model": "UCD2", "version": "0.1.0", "discovery_type": "NET", "timestamp": "2022-11-07T07:46:04.370629Z"}, {"id": "sim.1", "configured": false, "friendly_name": "Simulated dock", "address": "127.0.0.1:946", "version": "0.1.2", "discovery_type": "NET", "timestamp": "2022-11-07T07:46:05.245759Z"}]}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "put": {"tags": ["dock"], "summary": "Start discovery of new docking stations.", "description": "Start device discovery over Bluetooth and mDNS. Bluetooth or network discovery can be disabled with a query\nparameter. By default the discovery automatically stops after 30 seconds. Use the GET status request to check on\ndiscovered devices or DELETE to stop discovery.\n\nBy default only new network devices are returned. If a dock is already configured it will be omitted from the\nresults, unless the query parameter `new=false` is set. Docks with Bluetooth enabled are always returned, since\nthis usually means that the dock needs to be re-configured.\n\n- If BT is disabled in the remote, the query parameter `bt` is ignored.\n- Emits the WebSocket event `dock_discovery` with `event_type: START` when discovery starts.\n- For each discovered device the WebSocket event `dock_discovery` with `event_type: DISCOVER` is emitted.\n- This operation clears any old discovered devices and won't be accessible anymore with the GET operation.\n", "operationId": "startDockDiscovery", "parameters": [{"name": "timeout", "in": "query", "description": "Timeout in seconds.", "required": false, "schema": {"type": "integer", "format": "int32", "default": 30, "minimum": 1, "maximum": 300}}, {"name": "bt", "in": "query", "description": "Use Bluetooth to discover new docks.", "required": false, "schema": {"type": "boolean", "default": true}}, {"name": "net", "in": "query", "description": "Query network to discover new docks.", "required": false, "schema": {"type": "boolean", "default": true}}, {"name": "new", "in": "query", "description": "Only return new devices, filter out already configured docks.", "required": false, "schema": {"type": "boolean", "default": true}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["dock"], "summary": "Stop discovery of new docking stations.", "description": "Stops the device discovery. The current discovery status is returned in the response. Already discovered devices\nwon't be returned and can still be retrieved with the GET operation.\n\nEmits the WebSocket event `dock_discovery` with `event_type: STOP`.\n", "operationId": "stopDockDiscovery", "responses": {"200": {"description": "Dock discovery status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockDiscoveryStatus"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/docks/discover/{dockId}": {"get": {"tags": ["dock"], "summary": "Get docking station discovery device status.", "description": "Returns the discovered docking station device.\n", "operationId": "getDockDiscoveryDeviceStatus", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"description": "Dock discovery status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockDiscoveryStatus"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["dock"], "summary": "Execute command on a discovered docking station.", "description": "Perform a WebSocket connection test with a discovered docking station. If the dock requires an API token, it must\nbe specified in the request body.  \nThe `IDENTIFY` command also blinks the status LED on the dock.\n\nResponse status codes:\n- `200`: successful operation: the connection test was successful and docking station metadata could be retrieved.\n- `404`: discovered dock with `dock_id` not found. Check if the discovery result is still available and has not\n         been deleted. This can happen after a timeout since the discovery, or if the discovery result has been\n         cleared with `DELETE /docks/discover`.\n- `503`: docking station connection could not be established.\n", "operationId": "executeCommandOnDiscoveredDock", "parameters": [{"$ref": "#/components/parameters/dock_id"}, {"name": "cmd", "in": "query", "description": "Command to execute.", "required": true, "schema": {"type": "string", "enum": ["CONNECTION_TEST", "IDENTIFY"]}}, {"name": "timeout", "in": "query", "description": "Timeout in seconds.", "required": false, "schema": {"type": "integer", "format": "int32", "default": 5, "minimum": 3, "maximum": 60}}], "requestBody": {"required": false, "description": "Command payload", "content": {"application/json": {"schema": {"description": "Driver connection parameters.", "type": "object", "properties": {"connection": {"type": "object", "properties": {"token": {"description": "Optional dock authentication token.\n", "type": "string", "maxLength": 40}}}}}}}}, "responses": {"200": {"description": "Dock system information", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockSystemInfo"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/docks/setup": {"get": {"tags": ["dock"], "summary": "Get current dock setup processes.", "description": "Return a list of all active setup process identifiers. The returned ids can be used with the\n`/docks/setup/:id` endpoints to continue or abort a setup process.\n", "operationId": "getDockSetupProcesses", "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"type": "array", "items": {"type": "string"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "post": {"tags": ["dock"], "summary": "Start setting up a new docking station.", "description": "Create a new setup process from a discovered dock or from a manually provided dock address.\n\n- If there's already a setup process running for the given dock id, status code `409` is returned.\n- Emits the WebSocket event `dock_setup_change` with `event_type: START` when this operation returns `201`.\n\nStart setup from dock discovery:\n- The required request data can be obtained from the `/api/docks/discover` endpoints when searching for docking\n  stations over Bluetooth or Ethernet. Simply provide the returned `DockDiscovery` data object (which is a super\n  set of the required data to start a setup process).\n- The returned `id` in the `DockSetupInfo` response will be the identifier for the next `PUT /docks/setup/:id`\n  call to provide additional data.\n\nManual setup:\n- A dock identifier will automatically be created and returned in `DockSetupInfo`.\n- The dock must be reachable on the network with the provided `custom_ws_url` and optional `token`. Otherwise,\n  status code `503` is returned.\n- The setup process is automatically started after a successful POST request, no call to `PUT /docks/setup/:id`\n  is required.\n\nResponse status codes:\n- `201`: setup process successfully started. Use `GET /docks/setup/:id` to poll for status updates, or listen to\n   WebSocket `dock_setup_change` event messages.\n- `400`: invalid data in request body.\n- `409`: a setup process is already running. Either wait until finished, or abort it.\n- `503`: service not available to setup docking station.  \n   E.g. Bluetooth is disabled and therefore the docking station cannot be setup over Bluetooth. Either enable\n   Bluetooth or setup the dock over Ethernet.\n", "operationId": "createDockSetup", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateDockSetup"}, "examples": {"From dock discovery": {"value": {"discovery": {"id": "UC-Dock-E831CDD012A8", "friendly_name": "Living room", "address": "192.168.1.106:946", "model": "UCD2", "version": "0.1.0", "discovery_type": "NET"}}}, "Manually": {"value": {"manually": {"name": "Living room", "token": "0000", "custom_ws_url": "192.168.1.106"}}}, "Manually with WiFi": {"value": {"manually": {"name": "Living room", "token": "0000", "custom_ws_url": "192.168.1.106", "wifi": {"ssid": "My network", "password": "don't tell anyone"}}}}}}}, "required": true}, "responses": {"201": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockSetupInfo"}, "examples": {"default": {"value": {"id": "UC-Dock-E831CDD012A8", "name": "Living room", "discovery_type": "NET", "state": "NEW"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["dock"], "summary": "Abort and remove all setup processes.", "description": "Stop all setup processes at the next possible operation and remove all setup process information.\n", "operationId": "stopAllDockSetups", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/docks/setup/{dockId}": {"get": {"tags": ["dock"], "summary": "Get docking station setup status.", "description": "Poll operation to retrieve the current docking station setup state. See the `state` and `error` fields in the\nresponse message. There are also WebSocket `dock_setup_change` event messages for state changes to avoid polling.\n\nDefined setup states:\n- `NEW`: setup has not yet been started. Use the `PUT` operation to provide the required data and to start setting up the dock.\n- `CONFIGURING`: setup data is currently being transferred to the dock.\n- `RESTARTING`: dock has been configured and is restarting to integrate into the network.\n- `OK`: setup process has been completed successfully, the dock can now be used.\n- `ERROR`: the setup process failed. Check the `error` field for more information.\n", "operationId": "getDockSetupStatus", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockSetupInfo"}, "examples": {"default": {"value": {"id": "UC-Dock-E831CDD012A8", "name": "Living room", "model": "UCD2_VIRTUAL", "discovery_type": "NET", "state": "OK"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["dock"], "summary": "Setup docking station.", "description": "Set required data to start the setup process and configure the docking station.\nWhen using Bluetooth the WiFi network name and credentials must be provided to connect the dock to the WiFi network.\n\nThe `state` field in the response message indicate the current state of the setup process. Use the `GET` operation\nto poll for state updates or listen to the corresponding WebSocket `dock_setup_change` event messages with\n`event_type: SETUP`.\n", "operationId": "startDockSetup", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockSetup"}, "examples": {"default": {"value": {"name": "Living room", "token": "123", "description": "Setup test", "wifi": {"ssid": "My Network", "password": "0123456789"}}}}}}, "required": true}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockSetupInfo"}, "examples": {"default": {"value": {"id": "UC-Dock-E831CDD012A8", "name": "Living room", "model": "UCD2", "discovery_type": "NET", "state": "CONFIGURING"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["dock"], "summary": "Abort the dock setup process.", "description": "Stop the setup process at the next possible operation and remove the setup process information.  \nTo start a new setup process, use the `POST /docks/setup` operation again.\n\nEmits the WebSocket event `dock_setup_change` with `event_type: STOP`.\n", "operationId": "stopDockSetup", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/docks/devices/{dockId}": {"get": {"tags": ["dock"], "summary": "Get dock configuration.", "description": "Returns the dock configuration, enriched with the current session information if a dock connection is established.\n", "operationId": "getDock", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockConfiguration"}, "examples": {"default": {"value": {"dock_id": "UC-Dock-E831CDD012A8", "name": "Living room", "resolved_ws_url": "ws://192.168.1.23:946", "active": true, "model": "UCD2", "revision": "5.4", "led_brightness": 88, "state": "ACTIVE", "version": "0.9.2", "learning_active": false, "description": "Setup test"}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "patch": {"tags": ["dock"], "summary": "Change dock configuration like auto-connect or access token.", "description": "Update one or more dock fields.\n\n- If the dock is in an `active` connection state, then the `name`, `token` and `wifi` values are persisted in the\n  dock if provided in the request. The request fails with `503` service unavailable if the configuration can't be\n  set in the docking station.\n- An empty `custom_ws_url` value will remove the custom URL.\n- If the dock is not active, the values are only stored in the remote. A changed `token` will be used for the next\n  connection attempt.\n", "operationId": "updateDock", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "requestBody": {"description": "Fields to update, omit the ones without change.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockUpdateRequest"}}}}, "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockConfiguration"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["dock"], "summary": "Start or stop a dock connection.", "description": "Establish or stop a session to the dock.  \nUse `GET /docks` or `GET /docks/devices/{dockId}` to check on the connection status.\n", "operationId": "dockConnectionCommand", "parameters": [{"$ref": "#/components/parameters/dock_id"}, {"name": "cmd", "in": "query", "description": "Command to execute.", "required": true, "schema": {"type": "string", "enum": ["CONNECT", "DISCONNECT"]}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["dock"], "summary": "Delete dock configuration.", "description": "\u26a0\ufe0f The dock configuration will be irrevocably deleted!\n\nAn active dock session will be disconnected and the persisted dock configuration removed.\n", "operationId": "deleteDock", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/docks/devices/{dockId}/command": {"post": {"tags": ["dock"], "summary": "Send a dock command.", "description": "The following `command` values are defined:\n- `SET_LED_BRIGHTNESS`: set the maximum brightness of the front indicator LED. Set the `0..100` percentage as\n   string parameter in the `value` field.\n- `SET_VOLUME`: 3\ufe0f\u20e3 set the speaker volume. Set the `0..100` percentage as\n   string parameter in the `value` field.\n- `IDENTIFY`: identify the dock with blinking the indicator LED.\n- `REMOTE_LOW_BATTERY`: trigger the low battery status indicator on the dock.\n- `REMOTE_CHARGED`: trigger the remote charged indicator on the dock.\n- `REMOTE_NORMAL`: trigger the normal remote operation mode on the dock.\n- `REBOOT`: reboot the dock.\n- `RESET`: \u26a0\ufe0f factory reset the dock. Requires administrator privileges.  \n   The dock configuration will be deleted from the remote.\n", "operationId": "dockCommand", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "requestBody": {"description": "Dock command", "content": {"application/json": {"schema": {"type": "object", "properties": {"command": {"type": "string", "enum": ["SET_LED_BRIGHTNESS", "SET_VOLUME", "IDENTIFY", "REMOTE_LOW_BATTERY", "REMOTE_CHARGED", "REMOTE_NORMAL", "REBOOT", "RESET"]}, "value": {"description": "Command parameter value. Required for `SET_LED_BRIGHTNESS`.", "type": "string"}}, "required": ["command"]}, "examples": {"Set LED brightness to 50%": {"value": {"command": "SET_LED_BRIGHTNESS", "value": "50"}}, "Set LED brightness to maximum": {"value": {"command": "SET_LED_BRIGHTNESS", "value": "100"}}, "Identify the dock": {"value": {"command": "IDENTIFY"}}, "Trigger low battery indicator": {"value": {"command": "REMOTE_LOW_BATTERY"}}, "Trigger remote charged indicator": {"value": {"command": "REMOTE_CHARGED"}}, "Reboot the dock": {"value": {"command": "REBOOT"}}}}}}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/docks/devices/{dockId}/update": {"get": {"tags": ["dock"], "summary": "Check for dock firmware updates.", "description": "Check if there is an update available for the dock.\n\nThis operation will use the cached update information from the software update cloud service, which runs\nperiodically to check for available updates and independently from this operation.  \nThe returned `update_check_enabled` flag indicates if the online update check is enabled or not.\n\nIf `update_id` is set then an update is currently in progress and can be monitored either with listening to the\nWebSocket `dock_update_change` event messages or polling the status with the\n`GET /docks/devices/{dockId}/update/{id}` operation.\n", "operationId": "checkDockFirmwareUpdate", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockUpdateCheck"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["dock"], "summary": "Force dock firmware update check.", "description": "Check if there is an update available for the dock.\n\nThis operation will contact the software update cloud service to check for available updates.    \nThe returned `update_check_enabled` flag indicates if the online update check is enabled or not.\n\nIf `update_id` is set then an update is currently in progress and can be monitored either with listening to the\nWebSocket `dock_update_change` event messages or polling the status with the\n`GET /docks/devices/{dockId}/update/{id}` operation.\n\nNew updates will automatically downloaded. The download state can be retrieved with the GET operation and is\nshown in the `firmware_update.download` enum field.\n", "operationId": "forceCheckDockFirmwareUpdate", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockUpdateCheck"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["dock"], "summary": "Update dock firmware.", "description": "Start a firmware update on the given dock. The returned update identifier can be used to poll for the update \nprogress with the `GET /docks/devices/{dockId}/update/{id}` operation or listen to the WebSocket\n`dock_update_change` event message.\n\nThe battery of the remote needs to be at least 20% charged to start the dock firmware update. \n\nError response codes:\n- `400`: Bad request if no update is available for the given dock.\n- `404`: Dock identifier not found.\n- `409`: Conflict, an update is already running. Use the `GET` operation to retrieve the current update identifier.\n- `503`: The dock is not connected, not enough battery to start the update, or the update service is unavailable.  \n         Please try again later.\n", "operationId": "updateDockFirmware", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"201": {"description": "Firmware update started", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["dock"], "summary": "\ud83d\udea7 Abort the dock firmware update.", "description": "Stop the firmware update process at the next possible operation and remove the update process information.\n\nEmits the WebSocket event `dock_update_change` with `event_type: STOP`\n", "operationId": "stopDockFirmwareUpdate", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/docks/devices/{dockId}/update/{id}": {"get": {"tags": ["dock"], "summary": "Check for dock firmware update progress.", "description": "Get the current progress and status information about a dock firmware upgrade.\n\nInstead of using polling one can also listen to the WebSocket `dock_update_change` event messages.\n", "operationId": "dockFirmwareUpdateProgress", "parameters": [{"$ref": "#/components/parameters/dock_id"}, {"name": "id", "in": "path", "description": "Update identification", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DockUpdateProgress"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/docks/devices/{dockId}/ir/send": {"get": {"tags": ["dock"], "summary": "Test IR command.", "description": "\u26a0\ufe0f This is for testing only. Please use the `/ir/emitters/` endpoints for sending IR codes.\n\nTest function for sending IR commands. The IR code can either be in Pronto format or Hex.\nIf no output is specified, the code will only be emitted from the dock.\n", "operationId": "sendIrTest", "parameters": [{"$ref": "#/components/parameters/dock_id"}, {"name": "int1", "in": "query", "description": "Main internal ir blaster", "schema": {"type": "boolean"}}, {"name": "int2", "in": "query", "description": "Second internal ir blaster. V2 dock: top", "schema": {"type": "boolean"}}, {"name": "ext1", "in": "query", "description": "External IR blaster 1", "schema": {"type": "boolean"}}, {"name": "ext2", "in": "query", "description": "External IR blaster 2", "schema": {"type": "boolean"}}, {"name": "pronto", "in": "query", "description": "Pronto IR code, values separated by comma", "required": false, "schema": {"type": "string", "pattern": "^[a-fA-F0-9]{4}(,[a-fA-F0-9]{4}){3,}$"}}, {"name": "hex", "in": "query", "description": "Hex IR code", "required": false, "schema": {"type": "string", "pattern": "^[\\d]{1,3};0x[a-fA-F0-9]{1,16};[\\d]{1,2};[\\d]{1,2}$"}}, {"name": "repeat", "in": "query", "description": "Optional repeat value for sending continuous IR repeat signals (depending on IR protocol).\n", "schema": {"type": "integer", "minimum": 0, "maximum": 20}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["dock"], "summary": "Send IR command.", "description": "\u26a0\ufe0f This is for testing only. Please use the `/ir/emitters/` endpoints for sending IR codes.\n\nSend an IR command, either in Pronto or [IRremoteESP8266 Hex](https://github.com/unfoldedcircle/IRremoteESP8266) format.\n\nHex format: `<protocol>;<hex-ir-code>;<bits>;<repeat-count>`\n- protocol: numeric value from supported and enabled protocols. See: [decode_type_t](https://github.com/unfoldedcircle/IRremoteESP8266/blob/v2.8.5-ucd2.2/src/IRremoteESP8266.h#L1011)\n- hex-ir-code: HEX value prefixed with `0x`\n- bits: number of bits in hex value\n- repeat-count: number of repeats\n", "operationId": "sendIr", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "requestBody": {"description": "IR command", "content": {"application/json": {"schema": {"type": "object", "properties": {"int1": {"description": "Main internal ir blaster", "type": "boolean"}, "int2": {"description": "Second internal ir blaster. V2 dock: top", "type": "boolean"}, "ext1": {"description": "External IR blaster 1", "type": "boolean"}, "ext2": {"description": "External IR blaster 2", "type": "boolean"}, "pronto": {"description": "Pronto IR code, values separated by space or comma", "type": "string", "pattern": "^0000((, )[a-fA-F0-9]{4}){5,}$"}, "hex": {"description": "Hex IR code", "type": "string", "pattern": "^[\\d]{1,3};0x[a-fA-F0-9]{1,16};[\\d]{1,2};[\\d]{1,2}$"}, "repeat": {"description": "Optional repeat value for sending continuous IR repeat signals (depending on IR protocol).\n", "type": "integer", "minimum": 0, "maximum": 20}}}}}}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/docks/devices/{dockId}/ports": {"get": {"tags": ["dock"], "summary": "\ud83e\uddea Get all external port configurations.", "description": "This operation returns the configuration of all external ports. A connection to the dock must have been established\nbefore, to retrieve the current configuration.\n\nSee the `PATCH` operation of an individual port for more information about the external port modes.\n", "operationId": "getAllDockPortConfigurations", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalPortConfigurations"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["dock"], "summary": "\ud83e\uddea Reset all external ports to their default mode.", "description": "This feature only works on supported docks. All external dock ports are configured to their default operation mode: \n- Dock Two: output ports cannot be reconfigured. This operation has no effect.\n- Dock 3: all ports are set to `AUTO` mode. The official IR-Blaster and IR-emitter are automatically detected.\n\nOnce a port has been reconfigured, the WebSocket event `dock_port_mode` is sent in the `docks` channel.\n", "operationId": "resetAllDockPortConfigurations", "parameters": [{"$ref": "#/components/parameters/dock_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/docks/devices/{dockId}/ports/{portId}": {"get": {"tags": ["dock"], "summary": "\ud83e\uddea Get external dock port configuration.", "description": "This operation returns the configuration of a given port. A connection to the dock must have been established\nbefore, to retrieve the current configuration.\n\nSee the `PATCH` operation for more information about the external port modes.\n", "operationId": "getDockPortConfiguration", "parameters": [{"$ref": "#/components/parameters/dock_id"}, {"$ref": "#/components/parameters/port_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalPortConfiguration"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "patch": {"tags": ["dock"], "summary": "\ud83e\uddea Configure an external dock port.", "description": "An external dock port is usually a 3.5 mm jack port for connecting IR-extenders and -blasters. Depending on the dock\nmodel, other operation modes are also supported. Use the `GET` operation to retrieve supported modes.\n\nThis feature only works on supported docks:\n- Dock Two: output ports cannot be reconfigured and this operation is not supported.\n- Dock 3: multiple modes are supported:\n  - `NONE`: The output port is disabled and has no function.\n  - `AUTO`: The official IR-Blaster and IR-emitter are automatically detected.\n  - `IR_BLASTER`: Infrared-blaster with a stereo-plug.\n  - `IR_EMITTER_MONO_PLUG`: Infrared-emitter from Dock Two with a mono-plug.\n  - `IR_EMITTER_STEREO_PLUG`: Infrared-emitter from Dock 3 with a stereo-plug.\n  - `TRIGGER_5V`: \ud83d\udea7 trigger support is not yet implemented.\n  - `RS232`: \ud83d\udea7 RS232 communication is not yet implemented.\n\nThe dock must be connected to the Remote to change its configuration. A manually created dock will show no supported\nmodes until a connection has been established and the supported modes retrieved.\n\nOnce a port has been reconfigured, the WebSocket event `dock_port_mode` is sent in the `docks` channel.\n\nResponse codes:\n- `200`: port configuration has been accepted. Depending on the mode, this operation might take a few seconds.\n- `400`: bad request, for example an unsupported or unknown mode.\n- `404`: either the dock identifier or port number is not valid.\n- `503`: dock connection is not available, configuration cannot be changed at the moment.\n", "operationId": "updateDockPortConfiguration", "parameters": [{"$ref": "#/components/parameters/dock_id"}, {"$ref": "#/components/parameters/port_id"}], "requestBody": {"description": "Entity data", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalPortConfigurationRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful operation returning the configured port in the response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalPortConfiguration"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["dock"], "summary": "\ud83e\uddea Reset external port configuration to its default mode.", "description": "This feature only works on supported docks. The specified dock port is configured to its default operation mode: \n- Dock Two: output ports cannot be reconfigured. This operation has no effect.\n- Dock 3: the port is set to `AUTO` mode. The official IR-Blaster and IR-emitter are automatically detected.\n\nOnce a port has been reconfigured, the WebSocket event `dock_port_mode` is sent in the `docks` channel.\n\nResponse codes:\n- `200`: port reset has been accepted. This operation might take a few seconds.\n- `404`: either the dock identifier or port number is not valid.\n- `503`: dock connection is not available, configuration cannot be reset at the moment.    \n", "operationId": "resetDockPortConfiguration", "parameters": [{"$ref": "#/components/parameters/dock_id"}, {"$ref": "#/components/parameters/port_id"}], "responses": {"200": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExternalPortConfiguration"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system": {"get": {"tags": ["system"], "summary": "Get system information.", "description": "Get hardware information about the device like serial number, model number and hardware revision.", "operationId": "getSystemInfo", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SystemInfo"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "post": {"tags": ["system"], "summary": "Perform a system command like reboot or power-off.", "description": "The following system commands can be executed:\n\n- `STANDBY`: Put the device into standby mode.\n- `REBOOT`: Reboot the device.\n- `POWER_OFF`: Switch off the device\n- `RESTART`: Restart all applications.\n- `RESTART_UI`: Restart the ui application.\n- `RESTART_CORE`: Restart the core service application.\n", "operationId": "systemCommand", "parameters": [{"name": "cmd", "in": "query", "description": "System command", "required": true, "schema": {"type": "string", "enum": ["STANDBY", "REBOOT", "POWER_OFF", "RESTART", "RESTART_UI", "RESTART_CORE"]}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/backup/export": {"get": {"tags": ["system"], "summary": "Create and export a device configuration backup.", "description": "Export the full UC Remote device configuration. This allows to restore the configuration after a factory reset\nor to load the configuration onto another device.\n\n- The backup archive is only returned to the client and not stored on the device. \n- The returned backup archive can be restored with `PUT /system/backup/restore`.\n- It is recommended to perform the backup while the remote is in the docking station.\n- Using the remote or the Core-API should be avoided while the backup is running.\n- The backup should only take a few seconds. The backup will take longer:\n  - if integration drivers are busy and require more time to shutdown.\n  - if many custom resources (icons, background images, etc) are present.\n\n\u26a0\ufe0f Attention:\n- The backup archive may contain personal information and access keys to external systems.\n  - The backup archive is not encrypted. Contained information can be extracted with little effort.\n  - For example the long-lived access token for Home Assistant is included, if that integration has been configured.\n- All integrations and docks will be disconnected and stopped during backup.\n  - They are restarted after the backup is finished. This may take several seconds until all entities are available again.\n  - Restart the device, if an integration or entities are no longer working after a backup.\n- The device must have enough free disk space to create the backup archive. At least 100 MB must be free to start the backup process.\n\nThe backup **does not include**:\n- WiFi network configuration and passwords.\n- Administrator pin.\n- Web-configurator pin.\n- Any API-keys created with the Core-API.\n\nError codes:\n- `403`: forbidden, only an administrator account may create a backup.\n- `409`: conflict, a backup or restore process is already running.\n- `507`: not enough disk space available.\n", "operationId": "exportBackup", "responses": {"200": {"description": "Binary backup archive.", "headers": {"content-disposition": {"description": "Attachment filename.", "schema": {"type": "string"}}}, "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "507": {"$ref": "#/components/responses/Err507InsufficientStorage"}}}}, "/system/backup/restore": {"put": {"tags": ["system"], "summary": "Upload and restore a device configuration backup.", "description": "Restore the UC Remote device configuration from the uploaded backup archive. The backup archive is only used\nto restore the system and deleted after restore.\n\n- It is highly recommended to perform the restore while the remote is in the docking station.\n- Using the remote or the Core-API should be avoided while the restore is running.\n- The restore should only take a few seconds. The restore will take longer:\n  - if integration drivers are busy and require more time to shutdown.\n  - if many custom resources (icons, background images, etc) are present.\n\n\u26a0\ufe0f Attention:\n- The device will not automatically restart after a system restore.\n  - The device must be restarted after the restore to activate all changed settings.\n  - Certain setting changes like OTA require a system restart.\n- WiFi configuration, administrator pin and web-configurator pin are not overwritten by a system restore.\n- All integrations and docks will be disconnected and stopped during restore.\n- The device must have enough free disk space to restore the backup. At least 100 MB must be free to start the restore process.\n\nError codes:\n- `400`: bad request, backup archive is invalid or corrupt. Check logs for further details.\n- `403`: forbidden, only an administrator account may restore a backup.\n- `409`: conflict, a backup or restore process is already running.\n- `500`: internal server error, the backup archive could not be processed. Check logs for further details.\n- `507`: not enough disk space available.\n", "operationId": "restoreBackup", "parameters": [{"$ref": "#/components/parameters/merge"}], "requestBody": {"content": {"multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"type": "string", "format": "binary"}}}}}}, "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BackupReports"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "500": {"$ref": "#/components/responses/Err500InternalServerError"}, "507": {"$ref": "#/components/responses/Err507InsufficientStorage"}}}}, "/system/backup/snapshots": {"get": {"tags": ["system"], "summary": "\ud83d\udc77 Get information about available system backup snapshots.", "description": "_Work in progress, might still change!_\n\nRetrieve all available device configuration backups stored on the device.\n", "operationId": "getBackupSnapshots", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/BackupSnapshot"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "post": {"tags": ["system"], "summary": "\ud83d\udc77 Create a new system backup snapshot.", "description": "_Work in progress, might still change!_\n\nCreate a new device configuration backup and store it on the device.\n\nPlease see `GET /system/backup/export` operation about creating a backup.\n\nResponse codes:\n- `403`: forbidden, only an administrator account may create a backup.\n- `409`: conflict, a maximum of 50 backups can be stored on the device, or a backup or restore process is already running.\n- `507`: a minimum of 100 MB free space on the device is required to create a new backup.\n", "operationId": "createBackupSnapshot", "responses": {"201": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BackupSnapshot"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "507": {"$ref": "#/components/responses/Err507InsufficientStorage"}}}, "delete": {"tags": ["system"], "summary": "\ud83d\udc77 Remove all system backups.", "description": "_Work in progress, might still change!_\n\nDelete all device configuration backups stored on the device.\n", "operationId": "deleteAllBackupSnapshots", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/backup/snapshots/{id}": {"get": {"tags": ["system"], "summary": "\ud83d\udc77 Get information about a system backup snapshot or download archive.", "description": "_Work in progress, might still change!_\n\nBased on the request `Content-Type` header, either the JSON metadata information is returned or the binary\nbackup archive. If the header is missing, the binary archive is returned.\n\nResponse codes:\n- `404`: system backup snapshot not found.\n", "operationId": "getBackupSnapshot", "parameters": [{"$ref": "#/components/parameters/backup_id"}], "responses": {"200": {"description": "Successful operation.", "headers": {"content-disposition": {"description": "Attachment filename for `content-type: application/octet-stream`.\n", "schema": {"type": "string"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BackupMetadata"}}, "application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "put": {"tags": ["system"], "summary": "\ud83d\udc77 Restore a system backup snapshot.", "description": "_Work in progress, might still change!_\n\nPlease see `PUT /system/backup/restore` operation about restoring a backup.\n\nResponse codes:\n- `403`: forbidden, only an administrator account may create a backup.\n- `404`: system backup snapshot not found.\n- `409`: conflict, a backup or restore process is already running.\n- `500`: internal server error, the backup archive could not be processed. Check logs for further details.\n- `507`: not enough disk space available.\n", "operationId": "restoreBackupSnapshot", "parameters": [{"$ref": "#/components/parameters/backup_id"}, {"$ref": "#/components/parameters/merge"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BackupReports"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "500": {"$ref": "#/components/responses/Err500InternalServerError"}, "507": {"$ref": "#/components/responses/Err507InsufficientStorage"}}}, "delete": {"tags": ["system"], "summary": "\ud83d\udc77 Remove a system backup snapshot.", "description": "_Work in progress, might still change!_\n", "operationId": "deleteBackupSnapshot", "parameters": [{"$ref": "#/components/parameters/backup_id"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/bt": {"put": {"tags": ["system"], "summary": "\ud83e\uddea Perform a Bluetooth operation.", "description": "Change the Bluetooth controller power mode or clear all bonding information.\n\n`power_mode`:\n- `On`: power-on the BT controller\n- `Off`: power-off the BT controller\n- `Sleep`: put the BT controller into HCI sleep mode\n", "operationId": "performBtOperation", "parameters": [{"name": "clear_bonds", "in": "query", "description": "Clear bonding data", "schema": {"type": "boolean"}}, {"name": "power_mode", "in": "query", "description": "Set power mode", "schema": {"type": "string", "enum": ["On", "Off", "Sleep"]}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["system"], "summary": "\ud83e\uddea Perform a Bluetooth subsystem reset.", "description": "A BT subsystem reset removes all bonding information and removes the BT-remote entity associations to BT connection \nprofiles.\n\nThe BT-remote entities are not removed, but they need to be paired again with a BT central device.\n", "operationId": "performBtReset", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/factory_reset": {"get": {"tags": ["system"], "summary": "Get factory reset token.", "description": "Get a factory reset token to perform a complete factory reset of the remote.\n\nThe token will be valid for 60 seconds. Afterwards, a new token must be requested.  \nWhenever a new token is requested, any old tokens will be invalidated.\n", "operationId": "getFactoryResetToken", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"type": "object", "properties": {"token": {"type": "string"}}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "post": {"tags": ["system"], "summary": "Perform a factory reset.", "description": "A factory reset removes all configuration data and puts the device into a clean state.  \n\n\u26a0\ufe0f **Warning:** All user data will be erased and won't be recoverable!\n\nA reset token must be requested first and provided to perform a factory reset.\n", "operationId": "performFactoryReset", "parameters": [{"name": "token", "in": "query", "description": "Reset token", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/install": {"get": {"tags": ["system"], "summary": "Get installed custom components.", "description": "Returns the installation status of custom system components like the user interface or web-configurator.\n", "operationId": "getInstalledCustomComponents", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/CustomInstall"}}, "examples": {"default": {"value": [{"component": "ui", "installed": true, "active": true, "installation_date": "2023-07-24T09:57:33+02:00", "release": {"name": {"en": "Remote UI"}, "version": "0.27.10", "description": {"en": "Custom remote UI App for testing."}, "developer": {"name": "Unfolded Circle ApS", "url": "https://www.unfoldedcircle.com", "email": "hello@unfoldedcircle.com"}, "home_page": "https://www.unfoldedcircle.com", "release_date": "2023-07-19", "requirements": {"firmware_version": ">=0.13.0, <1.0.0"}}}, {"component": "web_configurator", "installed": false, "active": false}]}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/install/{customComponent}": {"get": {"tags": ["system"], "summary": "Get status of a custom component installation.", "description": "Returns the status of an installed custom component, as a custom UI app or web-configurator.\n\n- Error response `400` might be returned, if the metadata of an installed custom component is no longer valid with\n  the current firmware.\n", "operationId": "getCustomComponentStatus", "parameters": [{"$ref": "#/components/parameters/custom_component"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CustomInstall"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "put": {"tags": ["system"], "summary": "Enable or disable a custom component.", "description": "Switch between a default or an installed custom component.\n\nThis does not delete the custom installation and only switches between the default component and the installed\ncustom component.\n\nError response codes:\n- `400`: metadata of custom component is no longer valid with the current firmware. \n- `403`: user doesn't have administrator rights.\n- `404`: the custom component is not installed and cannot be enabled or disabled.\n- `409`: installed custom component is no longer compatible with the current firmware.\n\n\u26a0\ufe0f Attention:\n- Switching the web-configurator might disconnect the current request. Use a GET request to check for the current state.\n- Switching the remote-ui will restart the application and the screen will go dark for a while.\n- For certain error conditions, the device might restart.\n", "operationId": "enableCustomComponent", "parameters": [{"$ref": "#/components/parameters/custom_component"}, {"name": "enable", "in": "query", "description": "Enable or disable component.", "required": true, "schema": {"type": "boolean"}}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CustomInstall"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}}}, "delete": {"tags": ["system"], "summary": "Remove an installed custom component.", "description": "Deactivates the custom components and starts the default one. The custom component is removed afterwards from the\ndevice.\n\n\u26a0\ufe0f Attention:\n- Deleting the web-configurator might disconnect the current request. Use a GET request to check for the current state.\n- Deleting an active, custom remote-ui will restart the application and the screen will go dark for a while.\n- For certain error conditions, the device might restart.\n", "operationId": "removeCustomComponent", "parameters": [{"$ref": "#/components/parameters/custom_component"}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}, "post": {"tags": ["system"], "summary": "Upload and install a custom component.", "description": "\u2622\ufe0f VOIDS WARRANTY \u2622\ufe0f\n\nThe `void_warranty` query parameter is required to install a custom component:\n- The user has to agree and confirm, that the warranty will be voided by installing a custom component.\n- The confirmation will be recorded in a write-once location on the device and cannot be reverted!\n- The value of the parameter must be `yes`, otherwise the installation is aborted and `401` returned. \n\nCustom archive requirements:\n- TAR GZip archive (either .tgz or .tar.gz file suffix).\n- In the root of the archive, there must be a `release.json` file describing the custom version.  \n  See `CustomRelease` schema for the release.json format.\n- No symlinks. They are automatically removed during the installation.\n- UI:\n  - The UI binary must be named `remote-ui` in the `./bin` subdirectory.\n  - All application files must be in one of the following subdirectories, other locations are not accessible at runtime:\n    - `./bin`: application binary, usually only `remote-ui`.\n    - `./config`: configuration data. Path is accessible with `UC_CONFIG_HOME` environment variable.\n    - `./data`: application data. Path is accessible with `UC_DATA_HOME` environment variable.\n- web-configurator:\n  - An `index.html` file must be in the root of the archive.\n\nError response codes:\n- `400`: invalid archive, missing data in archive or included metadata cannot be read.\n- `403`: user did not agree to void warranty, or user does not have administrator rights.\n- `409`: custom component is not compatible with the current firmware.\n- `507`: insufficient storage to upload and process installation archive.\n\n\u26a0\ufe0f Attention:\n- Installing a custom web-configurator might disconnect the current request. Use a GET request to check for the current state.\n- Installing a custom remote-ui will restart the application and the screen will go dark for a while.\n- For certain error conditions, the device might restart.\n", "operationId": "installCustomComponent", "parameters": [{"$ref": "#/components/parameters/custom_component"}, {"name": "void_warranty", "in": "query", "description": "User confirmation that this action voids warranty.", "required": false, "schema": {"type": "string"}}], "requestBody": {"content": {"multipart/form-data": {"schema": {"type": "object", "properties": {"file": {"description": "TAR GZip Archive file with the custom component. File extension must be `.tar.gz` or `.tgz`.", "type": "string", "format": "binary"}}}}}}, "responses": {"201": {"description": "Custom component successfully installed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CustomInstall"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "507": {"$ref": "#/components/responses/Err507InsufficientStorage"}}}}, "/system/logs": {"get": {"tags": ["system"], "summary": "Retrieve and query log entries.", "description": "Retrieve log entries based on the query parameters.\n\nDepending on the `Content-Type` header, the logs are either returned as JSON objects or exported as a text file.\n\n- `Content-Type: application/json` or none: retrieve logs as json objects.\n- `Content-Type: text/plain` or none: retrieve logs as text export.\n  - Field order: <timestamp> <service> <level> <message>\n  - Fields are separated by a tab.\n  - The message itself might contain tabs as well!\n  - The message might contain line breaks and use multiple lines.\n\nNotes:    \n- Number of log entries are limited to a maximum of 10'000 entries.\n- Log entries are retrieved in reverse order.\n- Not all services are using the priority logging yet and log all entries with priority 6 (info).  \n  They might even include their own log level in the message text.\n- Text search is not case-sensitive. Wildcards or Regex is not supported.\n", "parameters": [{"name": "p", "in": "query", "description": "Minimum priority of log message.", "required": false, "schema": {"type": "integer", "minimum": 0, "maximum": 8, "default": 5}}, {"name": "s", "in": "query", "description": "One or more service identifiers, separated by comma", "required": false, "schema": {"type": "string"}}, {"name": "limit", "in": "query", "description": "Limit number of returned log entries", "required": false, "schema": {"type": "integer", "minimum": 0, "maximum": 10000, "default": 100}}, {"name": "from", "in": "query", "description": "Oldest log timestamp to consider", "required": false, "schema": {"type": "string", "format": "date-time"}}, {"name": "to", "in": "query", "description": "Newest log timestamp to consider", "required": false, "schema": {"type": "string", "format": "date-time"}}, {"name": "q", "in": "query", "description": "Search text in log message", "required": false, "schema": {"type": "string"}}, {"name": "boot_ids", "in": "query", "description": "One or more boot identifiers, separated by comma", "required": false, "schema": {"type": "string"}}], "operationId": "queryLogs", "responses": {"200": {"description": "Successful operation.", "content": {"text/plain": {"schema": {"type": "string"}, "examples": {"default": {"value": "2023-07-27T09:11:44.584555+00:00  ui  WARN  A warning message\n2023-07-27T08:52:54.609843+00:00  ui  INFO  An information message\n2023-07-27T08:52:53.609143+00:00  ui  DEBUG Application is starting\n"}}}, "application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/SystemLogEntry"}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/logs/boots": {"get": {"tags": ["system"], "summary": "Get boot identifiers for log access.", "description": "List system boots to retrieve boot identifiers for a specific boot.\n", "operationId": "getBootLogIdentifiers", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/SystemLogBoot"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/logs/services": {"get": {"tags": ["system"], "summary": "Get available services to retrieve log entries from.", "description": "List the available services which can be queried for log entries.\n", "operationId": "getLogServices", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"type": "array", "items": {"$ref": "#/components/schemas/SystemLogService"}}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/logs/hci": {"get": {"tags": ["system"], "summary": "Download HCI trace file.", "description": "Retrieve the Bluetooth HCI trace file in binary PacketLogger file format.\n\n- `404 Not Found` is returned if there's no HCI trace file.\n", "operationId": "downloadHciLog", "responses": {"200": {"description": "Successful operation.", "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/system/logs/web": {"get": {"tags": ["system"], "summary": "Get the log-streaming web app configuration.", "description": "Retrieve the log-streaming web app configuration.\n", "operationId": "getLogWebAppCfg", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SystemLogWebAppCfg"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}, "put": {"tags": ["system"], "summary": "Configure log-streaming web app.", "description": "- The web-app can be started and stopped with the `enable` flag.\n- The `autostart` flag controls the automatic start after boot. If autostart is disabled, the web-app can still be\n  started and stopped manually.\n- Log frontend URL: `/log`.\n- The password to access the web app is optional:\n  - It needs to be at least 6 characters long, maximum length is 30 characters.\n  - Allowed characters: letters, numbers and special characters `*@^(){}[]=,.:_-`\n- An empty password value will disable the password, a missing password field doesn't change an existing password.\n", "operationId": "setLogWebAppCfg", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SystemLogWebAppCfg"}}}}, "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SystemLogWebAppCfg"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/power": {"get": {"tags": ["system"], "summary": "Get current system power mode and duration to enter standby.", "description": "Returns the current power mode of the device, if a power-supply is connected and the duration in seconds until the\nthe device will enter standby.\n\n- `standby_timeout_sec` is not returned if standby is disabled or the device is currently in the process of entering\n  or exiting standby.\n- `standby_timeout_sec` can return `0` without the device going into standby.  \n  This is the case if `power_supply: true` is set. As soon as the power supply is offline, the device will enter\n  standby after a few seconds if no input activity is registered.\n", "operationId": "getPowerMode", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PowerModeResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "put": {"tags": ["system"], "summary": "Set a power mode", "description": "Setting `SUSPEND` will put the system immediately into suspend mode!\n\nNote: suspend mode might be prevented by standby inhibitors, for example by activity sequences or if an integration\nsetup is running.\n", "operationId": "setPowerMode", "parameters": [{"$ref": "#/components/parameters/power_mode"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/power/battery": {"get": {"tags": ["system"], "summary": "Get battery status.", "operationId": "getBatteryStatus", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatteryStatusResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/power/charger": {"get": {"tags": ["system"], "summary": "Get battery charger information.", "description": "Device features:\n- `DOCK_CHARGING`: device can be charged in docking station (UCR2, UCR3).\n- `WIRELESS_CHARGING`: device has wireless charging support (UCR3).\n", "operationId": "getBatteryCharger", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatteryCharger"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "put": {"tags": ["system"], "summary": "\ud83d\udc77 Enable or disable wireless charging.", "description": "This operation is only supported on devices with wireless charging.\n", "operationId": "updateBatteryCharger", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatteryChargerUpdate"}}}}, "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BatteryCharger"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/power/standby_inhibitors": {"get": {"tags": ["system"], "summary": "Get standby inhibitors.", "operationId": "getStandbyInhibitors", "description": "Automatic system standby can be prevented with \"standby inhibitors\". For example during integration setup or as a\nuser option for activities.\n\nThere are two types of inhibitors:\n- Temporary inhibitors set a delay value for which the device doesn't go into standby. After the delay and\n  the idle timeouts have expired, the remote goes into standby and the temporary inhibitor will be removed.\n- Blocking inhibitors will prevent the device to go into standby until the inhibitor is removed by the client.\n", "responses": {"200": {"description": "List of inhibitors.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Inhibitors"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "post": {"tags": ["system"], "summary": "Create a standby inhibitor.", "operationId": "createStandbyInhibitor", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateStandbyInhibitor"}}}, "required": true}, "responses": {"201": {"description": "Successful operation.", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "409": {"$ref": "#/components/responses/Err409Conflict"}}}, "delete": {"tags": ["system"], "summary": "Remove all standby inhibitors.", "operationId": "deleteAllStandbyInhibitors", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/power/standby_inhibitors/{id}": {"delete": {"tags": ["system"], "summary": "Remove a standby inhibitor.", "operationId": "deleteStandbyInhibitor", "parameters": [{"name": "id", "in": "path", "description": "Inhibitor identifier", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}}}}, "/system/sensors/ambient_light": {"get": {"tags": ["system"], "summary": "Get current ambient light reading from light sensor.", "operationId": "getAmbientLight", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AmbientLight"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/update": {"get": {"tags": ["system"], "summary": "Check if system update is available.", "description": "Returns the known available system updates.\n\nSystem update checks are run automatically (if not disabled in settings). Use the `PUT` operation to force\nan update check.\n", "operationId": "checkSystemUpdate", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AvailableSystemUpdateResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "put": {"tags": ["system"], "summary": "Force system update check", "operationId": "forceSystemUpdateCheck", "description": "Contacts the update server to check if a new system update is available.\n", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AvailableSystemUpdateResponse"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/update/{updateId}": {"post": {"tags": ["system"], "summary": "Perform system update.", "description": "Start a system update with the given `updateId` parameter. Use `latest` to use the latest available system update.\n\nThe system update will be started if:\n- the system update has been downloaded already (`download` state is `DOWNLOADED`).\n- the device has at least 50% battery charge.\n\nIf the system update is started, the response message contains `state: START`. In case there's not enough battery,\n`503 service unavailable` is returned. \nIt is recommended to perform the update while the remote is charging in the docking station.\n\nThe progress of the system update can be retrieved with the `GET` operation, or by listening to the WebSocket \n`software_update` event messages.\n\nIf the system update hasn't been downloaded yet (`download` state is `PENDING` or `ERROR`), this operation will only\nstart the download and return `state: DOWNLOAD`. Once successfully downloaded, it can be installed by calling this\noperation again.\n\nThe download process emits `software_update` progress event messages with `event_type: PROGRESS` and `state: DOWNLOAD`.\nThe payload fields `download_bytes`, `download_percent` and `update_id` are set.  \n\n- A successful download is indicated with `download_percent: 100`, without the `download_bytes` field.\n- The state is set to `FAILURE` if a download fails.\n- Depending on download speed, `download_percent` might skip certain values or report the same value multiple times.\n- The famous last percent will take longer due to image validation.\n\nExample download progress events:    \n- Download progress event:\n```json\n{\n  \"kind\": \"event\",\n  \"msg\": \"software_update\",\n  \"cat\": \"REMOTE\",\n  \"ts\": \"2024-09-30T16:25:18.668395688Z\",\n  \"msg_data\": {\n    \"event_type\": \"PROGRESS\",\n    \"progress\": {\n      \"download_bytes\": 256734720,\n      \"download_percent\": 97,\n      \"state\": \"DOWNLOAD\",\n      \"update_id\": \"some-id\"\n    },\n    \"update_id\": \"some-id\"\n  }\n}\n```\n- Final success event:\n```json\n{\n  \"kind\": \"event\",\n  \"msg\": \"software_update\",\n  \"cat\": \"REMOTE\",\n  \"ts\": \"2024-09-30T16:25:34.229442566Z\",\n  \"msg_data\": {\n    \"event_type\": \"PROGRESS\",\n    \"progress\": {\n      \"download_percent\": 100,\n      \"state\": \"DOWNLOAD\",\n      \"update_id\": \"some-id\"\n    },\n    \"update_id\": \"some-id\"\n  }\n}\n```\n\nError codes:\n- `404`: updateId does not exist\n- `409`: download or update is already running\n- `422`: for download request: update is already downloaded\n- `503`: update service is currently not available\n", "operationId": "updateSystem", "parameters": [{"name": "updateId", "in": "path", "description": "Update image identification", "required": true, "schema": {"type": "string", "default": "latest"}}], "responses": {"201": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SystemUpdateResponse"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "422": {"$ref": "#/components/responses/Err422UnprocessableEntity"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "get": {"tags": ["system"], "summary": "Get system update progress.", "operationId": "getSystemUpdateProgress", "parameters": [{"name": "updateId", "in": "path", "description": "Update image identification", "required": true, "schema": {"type": "string", "default": "latest"}}], "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SystemUpdateProgress"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}}}}, "/system/wifi": {"get": {"tags": ["system"], "summary": "Get WiFi status.", "operationId": "getWifiStatus", "responses": {"200": {"description": "Successful operation.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WifiStatus"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "put": {"tags": ["system"], "summary": "WiFi connection handling.", "description": "Perform one of the following commands on the WLAN interface:\n\n- `DISCONNECT`: Disconnect and wait for `REASSOCIATE` or `RECONNECT` command before connecting again.\n- `RECONNECT`: Connect if disconnected (i.e. like `REASSOCIATE`, but only connect if in disconnected state).\n- `REASSOCIATE`: Force reassociation.\n- `ENABLE_ALL_NETWORKS`: Enable all network connections and start connecting to a network if in disconnected state.\n- `DISABLE_ALL_NETWORKS`: Disable all network connections and disconnect if in connected state.\n\n\u26a0\ufe0fAttention: `ENABLE_ALL_NETWORKS` and `DISABLE_ALL_NETWORKS` will persist the state! I.e. if all networks are \ndisabled and the device is restarted afterwards, no WiFi connection will be established.\n", "operationId": "wifiCommand", "parameters": [{"name": "cmd", "in": "query", "description": "Command", "schema": {"$ref": "#/components/schemas/WifiCmd"}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/wifi/scan": {"get": {"tags": ["system"], "summary": "Get discovered WiFi access points.", "description": "Returns the current discovery status and any discovered access points.\n\nUse the DELETE operation to stop an active discovery and PUT to start a new discovery.\n", "operationId": "getWifiScanStatus", "responses": {"200": {"description": "WiFi AP discovery status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApScanStatus"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "put": {"tags": ["system"], "summary": "Start discovery of WiFi access points.", "description": "Request a new BSS scan. A scan usually takes a few seconds and the current state is returned with the GET\noperation, together with the already found access points.\n\nError responses:\n- `409` conflict: a scan is already active, please try again later.\n- `503` service unavailable: wifi is not available.\n", "operationId": "startWifiScan", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "409": {"$ref": "#/components/responses/Err409Conflict"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["system"], "summary": "Stop discovery of WiFi access points.", "description": "Stops the access point discovery. The current discovery status is returned in the response.\n", "operationId": "stopWifiScan", "responses": {"200": {"description": "WiFi scan status", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApScanStatus"}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/wifi/networks": {"get": {"tags": ["system"], "summary": "Get configured WiFi networks.", "description": "Returns all configured WiFi networks.\n", "operationId": "getAllWifiNetworks", "responses": {"200": {"description": "Configured WiFi networks.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SavedNetworks"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "post": {"tags": ["system"], "summary": "Create a new Wifi network configuration.", "operationId": "addWifiNetwork", "description": "Add a new network configuration for the given SSID.  \nFor an open network without password the `password` field must be omitted (do not send an empty password value).\n\n\u26a0\ufe0f Only WPA-PSK (pre shared keys) and open networks are supported!\n", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateWifiNetwork"}}}}, "responses": {"201": {"description": "Successful operation.", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "integer"}}}}}}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["system"], "summary": "Delete all configured WiFi networks.", "description": "Disconnects the WiFi network and removes all network configurations.\n\n\u26a0\ufe0f Attention: the network configuration is automatically persisted and the network configuration cannot\nbe retrieved anymore!\n", "operationId": "deleteAllWifiNetworks", "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}, "/system/wifi/networks/{wifiId}": {"get": {"tags": ["system"], "summary": "Get WiFi network configuration.", "description": "Returns the configured wifi network.\n\nUse the DELETE operation to remove and PATCH to edit a network configuration. A new network configuration can be\ncreated with the POST operation on the `/system/wifi/networks/` resource.\n", "operationId": "getWifiNetwork", "parameters": [{"$ref": "#/components/parameters/wifi_id"}], "responses": {"200": {"description": "WiFi network configuration", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SavedNetwork"}}}}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "patch": {"tags": ["system"], "summary": "Modify a network configuration.", "description": "Change the WiFi network password.", "operationId": "modifyWifiNetwork", "parameters": [{"$ref": "#/components/parameters/wifi_id"}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModifyWifiNetwork"}}}}, "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "400": {"$ref": "#/components/responses/Err400BadRequest"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "put": {"tags": ["system"], "summary": "WiFi network connection handling.", "description": "Perform one of the following commands on a network configuration:\n- `ENABLE`: Enable a network. If no network is connected, it will be tried to connect to this network.\n- `DISABLE`: Disable a network. If the network is currently connected it will be disconnected.\n- `SELECT`: Select the given network and disable all others.\n\n\u26a0\ufe0f Attention: all network changes (enabled or disabled) are persisted!\n", "operationId": "wifiNetworkCommand", "parameters": [{"$ref": "#/components/parameters/wifi_id"}, {"name": "cmd", "in": "query", "description": "Command", "schema": {"$ref": "#/components/schemas/WifiNetworkCmd"}}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}, "delete": {"tags": ["system"], "summary": "Delete a configured WiFi network.", "description": "The given network is removed from the configuration and disconnected if currently connected.\n\n\u26a0\ufe0f Attention: the network configuration is automatically persisted and the removed network configuration cannot\nbe retrieved anymore!\n", "operationId": "deleteWifiNetwork", "parameters": [{"$ref": "#/components/parameters/wifi_id"}], "responses": {"200": {"$ref": "#/components/responses/SuccessMessage"}, "401": {"$ref": "#/components/responses/Err401Unauthorized"}, "403": {"$ref": "#/components/responses/Err403Forbidden"}, "404": {"$ref": "#/components/responses/Err404NotFound"}, "503": {"$ref": "#/components/responses/Err503ServiceUnavailable"}}}}}, "components": {"parameters": {"active": {"name": "active", "in": "query", "description": "Filter by active flag", "required": false, "schema": {"type": "boolean"}}, "page": {"name": "page", "in": "query", "description": "Current page number. 1-based.", "required": false, "schema": {"type": "integer", "format": "int32", "default": 1, "minimum": 1}}, "limit": {"name": "limit", "in": "query", "description": "Limits the number of returned items.", "required": false, "schema": {"type": "integer", "format": "int32", "default": 10, "minimum": 10, "maximum": 100, "multipleOf": 10}}, "api_key_id": {"name": "apiKeyId", "in": "path", "description": "API key identification", "required": true, "schema": {"$ref": "#/components/schemas/ApiKeyId"}}, "token_type": {"name": "type", "in": "query", "description": "Token type.", "required": false, "schema": {"$ref": "#/components/schemas/ExtTokenType"}}, "system": {"name": "system", "in": "path", "description": "Identification of the external system. E.g. _homeassistant_.", "required": true, "schema": {"$ref": "#/components/schemas/ExternalSystemId"}}, "tokenId": {"name": "tokenId", "in": "path", "description": "Access token identification", "required": true, "schema": {"$ref": "#/components/schemas/AccessTokenId"}}, "resource_type_query": {"name": "type", "in": "query", "description": "Resource type.", "required": false, "schema": {"$ref": "#/components/schemas/ResourceType"}}, "resource_type": {"name": "type", "in": "path", "description": "Resource type", "required": true, "schema": {"$ref": "#/components/schemas/ResourceType"}}, "query": {"name": "q", "in": "query", "description": "Text search", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 50}}, "resource_id": {"name": "id", "in": "path", "description": "Resource identifier", "required": true, "schema": {"type": "string"}}, "driver_id": {"name": "driverId", "in": "path", "description": "Integration driver identification", "required": true, "schema": {"$ref": "#/components/schemas/DriverId"}}, "enabled": {"name": "enabled", "in": "query", "description": "Filter by enabled flag.", "required": false, "schema": {"type": "boolean"}}, "instantiable": {"name": "instantiable", "in": "query", "description": "Filter if a driver is instantiable or not:\n- true = only consider drivers which allow new integration instances to be created from. Either single-device drivers\n  without an instance, or multi-device drivers.\n- false = only drivers which allow no more instances\n- NONE = any.\n", "required": false, "schema": {"type": "boolean"}}, "single_device": {"name": "single_device", "in": "query", "description": "true = only consider single-device drivers, false = only multi-device drivers, NONE = all.\n", "required": false, "schema": {"type": "boolean"}}, "has_instances": {"name": "has_instances", "in": "query", "description": "Filter if a driver has integration instances or not:\n- true = only consider drivers which have at least one integration instance,\n- false = drivers without instances\n- NONE = any.\n", "required": false, "schema": {"type": "boolean"}}, "integration_id": {"name": "intgId", "in": "path", "description": "Integration identification", "required": true, "schema": {"$ref": "#/components/schemas/IntegrationId"}}, "entity_types": {"name": "entity_types", "in": "query", "description": "Filter by multiple entity types, separated by comma.", "required": false, "schema": {"type": "string"}}, "entity_id": {"name": "entityId", "in": "path", "description": "Entity identification.", "required": true, "schema": {"$ref": "#/components/schemas/EntityId"}}, "integration_ids": {"name": "intg_ids", "in": "query", "description": "Filter by multiple integration identifiers, separated by comma.", "required": false, "schema": {"type": "string"}}, "exclude": {"name": "exclude", "in": "query", "description": "Exclude entities from activity, macro, profile page and group identifiers, separated by comma.", "required": false, "schema": {"type": "string"}}, "media_id": {"name": "media_id", "in": "query", "description": "The media ID to browse.", "required": false, "schema": {"type": "string"}}, "media_type": {"name": "media_type", "in": "query", "description": "The media type to browse.", "required": false, "schema": {"type": "string"}}, "stable_ids": {"name": "stable_ids", "in": "query", "description": "Use stable media identifiers.", "required": false, "schema": {"type": "boolean"}}, "button_id": {"name": "buttonId", "in": "path", "description": "Button identification.", "required": true, "schema": {"$ref": "#/components/schemas/ButtonId"}}, "button_press": {"name": "buttonPress", "in": "path", "description": "Button press type.", "required": true, "schema": {"type": "string", "enum": ["short_press", "long_press"]}}, "page_id": {"name": "pageId", "in": "path", "description": "Page identification", "required": true, "schema": {"$ref": "#/components/schemas/SimpleId"}}, "group_id": {"name": "groupId", "in": "path", "description": "Group identification", "required": true, "schema": {"$ref": "#/components/schemas/SimpleId"}}, "ir_key": {"name": "key", "in": "path", "description": "IR command key", "required": true, "schema": {"$ref": "#/components/schemas/IrCodeKey"}}, "emitter_id": {"name": "emitterId", "in": "path", "description": "Emitter device id.", "required": true, "schema": {"$ref": "#/components/schemas/SimpleId"}}, "cmd_id": {"name": "cmdId", "in": "path", "description": "IR command identification.", "required": true, "schema": {"$ref": "#/components/schemas/IrCodeKey"}}, "profile_id": {"name": "profileId", "in": "path", "description": "Profile identification", "required": true, "schema": {"$ref": "#/components/schemas/SimpleId"}}, "dock_id": {"name": "dockId", "in": "path", "description": "Dock identification", "required": true, "schema": {"$ref": "#/components/schemas/DockId"}}, "port_id": {"name": "portId", "in": "path", "description": "Dock port number", "required": true, "schema": {"type": "integer", "minimum": 1}}, "merge": {"name": "merge", "in": "query", "description": "Merge data.", "required": false, "schema": {"type": "boolean"}}, "backup_id": {"name": "id", "in": "path", "description": "Backup snapshot identifier", "required": true, "schema": {"type": "string"}}, "custom_component": {"name": "customComponent", "in": "path", "description": "Custom system component.", "required": true, "schema": {"$ref": "#/components/schemas/CustomComponent"}}, "power_mode": {"name": "power_mode", "in": "query", "description": "Power mode", "required": true, "schema": {"$ref": "#/components/schemas/PowerMode"}}, "wifi_id": {"name": "wifiId", "in": "path", "description": "WiFi network identification", "required": true, "schema": {"type": "integer", "minimum": 0}}, "token_id": {"$ref": "#/components/parameters/tokenId"}, "intg_ids": {"$ref": "#/components/parameters/integration_ids"}}, "schemas": {"VersionInfo": {"type": "object", "properties": {"model": {"description": "Short model identifier of the remote (UCR2 for Remote Two, UCR3 for Remote 3).\n", "type": "string"}, "device_name": {"description": "Custom name of the remote", "type": "string"}, "hostname": {"description": "Hostname of the remote", "type": "string"}, "address": {"description": "MAC address of the remote", "type": "string"}, "api": {"description": "API version", "type": "string"}, "core": {"description": "Core service version", "type": "string"}, "ui": {"description": "Frontend app version", "type": "string"}, "os": {"description": "Operating system version", "type": "string"}, "integrations": {"description": "Versions of the available integrations. Map of (integration_name, version).", "type": "object", "additionalProperties": {"type": "string"}}}}, "HealthStatus": {"type": "string", "enum": ["Healthy", "Degraded", "Unhealthy"]}, "ApiResponse": {"type": "object", "properties": {"code": {"type": "string", "description": "Status code"}, "message": {"type": "string", "description": "Status message describing the result or error. This message is intended for error analysis and should not directly shown to the end user."}}}, "LoginRequest": {"type": "object", "properties": {"username": {"type": "string"}, "password": {"type": "string"}}, "required": ["username", "password"], "examples": [{"username": "admin", "password": "1234"}]}, "FieldValidationError": {"type": "object", "properties": {"code": {"description": "Validation error code. This can be a custom code or one of the common pre-defined codes:\n- `LENGTH`: String is either too short or too long.\n- `RANGE`: Number is not in valid range.\n- `REGEX`: Regex validation failed.\n- `INVALID_FORMAT`: value is in an invalid format.\n", "type": "string"}, "message": {"description": "Validation rule message.", "type": "string"}, "params": {"description": "Optional code related parameters. E.g. `min`, `max` for string-length or number-range validation.", "type": "object"}}, "required": ["message"]}, "ValidationError": {"type": "object", "properties": {"field": {"description": "Field identifier with an invalid value.", "type": "string"}, "field_errors": {"description": "Optional field validation error descriptions. A field can have multiple validation rules with an error.\n", "type": "array", "items": {"$ref": "#/components/schemas/FieldValidationError"}}}, "required": ["field"]}, "ValidationErrorResponse": {"type": "object", "properties": {"code": {"type": "string", "description": "Error code"}, "message": {"type": "string", "description": "Message describing the validation error. This message is intended for error analysis and should not directly shown to the end user."}, "errors": {"description": "Optional validation errors", "type": "array", "items": {"$ref": "#/components/schemas/ValidationError"}}}}, "ApiKeyId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 36, "description": "Unique key identifier. Usually a UUID."}, "ApiKeyName": {"type": "string", "minLength": 1, "maxLength": 50, "description": "Friendly API key name to show in the app"}, "ScopeName": {"type": "string", "format": "^[a-zA-Z\\-:]+$", "minLength": 1, "maxLength": 36, "description": "Permission scope name"}, "Description": {"type": "string", "maxLength": 255, "description": "Optional description"}, "ApiKey": {"type": "object", "properties": {"key_id": {"$ref": "#/components/schemas/ApiKeyId"}, "name": {"$ref": "#/components/schemas/ApiKeyName"}, "prefix": {"description": "Prefix of the API key for identification purposes.", "type": "string"}, "active": {"type": "boolean", "description": "Only activated keys are valid for API access."}, "valid_to": {"type": "string", "format": "date-time", "description": "Optional expiration timestamp. If not set, the API key is valid until revoked."}, "scopes": {"type": "array", "items": {"$ref": "#/components/schemas/ScopeName"}}, "description": {"$ref": "#/components/schemas/Description"}, "creation_date": {"type": "string", "format": "date-time"}}}, "ApiKeys": {"type": "array", "items": {"$ref": "#/components/schemas/ApiKey"}}, "ApiKeyRequest": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/ApiKeyName"}, "scopes": {"type": "array", "items": {"type": "string"}, "description": "Requested access scopes for the API key."}, "active": {"type": "boolean", "default": false, "description": "Only activated keys are valid for API access.  \nThis might be overridden if the requestor doesn't have sufficient rights. In this case the key will not be active\nuntil a user with appropriate rights will set it active. The assigned `active` state will be returned in the\nresponse.\n"}, "valid_to": {"type": "string", "format": "date-time", "description": "Optional expiration timestamp. If not set, the API key is valid until revoked."}, "description": {"$ref": "#/components/schemas/Description"}}, "required": ["name", "scopes"]}, "ApiKeyResponse": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/ApiKeyName"}, "api_key": {"type": "string", "description": "API key."}, "active": {"type": "boolean", "description": "Only activated keys are valid for API access."}, "valid_to": {"type": "string", "format": "date-time", "description": "Optional expiration timestamp. If not set, the API key is valid until revoked."}, "scopes": {"type": "array", "items": {"$ref": "#/components/schemas/ScopeName"}}}, "required": ["name", "api_key", "active", "scopes"]}, "ApiKeyUpdate": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/ApiKeyName"}, "active": {"type": "boolean", "description": "Only activated keys are valid for API access."}, "valid_to": {"type": "string", "format": "date-time", "description": "Optional expiration timestamp. If not set, the API key is valid until revoked."}, "description": {"$ref": "#/components/schemas/Description"}}}, "Scope": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/ScopeName"}, "description": {"type": "string", "description": "Permission scope description"}}, "required": ["name"]}, "Scopes": {"type": "array", "items": {"$ref": "#/components/schemas/Scope"}}, "ExtTokenType": {"description": "Type of the access token:\n- `TOKEN`: generic token, for example a long-lived access token.\n- `OAUTH2_APP`: OAuth2 application credentials.\n- `OAUTH2_TOKEN`: OAuth2 token (access and refresh tokens).\n", "type": "string", "enum": ["TOKEN", "OAUTH2_APP", "OAUTH2_TOKEN"]}, "ExtSystemState": {"description": "State of the external system:\n- `ALL`: all external systems.\n- `NEW`: external systems that have no stored credentials yet.\n- `ACTIVE`: external systems that have at least one stored credential.\n", "type": "string", "enum": ["ALL", "NEW", "ACTIVE"]}, "ExternalSystemId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 50, "description": "Unique external system identifier registered by an R2 integration to interact with the API."}, "ExtSystemName": {"type": "string", "minLength": 1, "maxLength": 50, "description": "Friendly name of the external system to display to the user within the app. This name must be unique for an external\nsystem and should be as short and concise as possible.\n"}, "TokenId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 36, "description": "Unique token identifier, used for later token management through the external system or management ui.\n"}, "DriverId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 36, "description": "Unique integration driver identifier, e.g. `homeassistant`, `homey`, etc."}, "LanguageText": {"type": "object", "description": "Key value pairs of language texts. Key: ISO 639-1 code with optional country suffix to represent a `culture code`.\nExamples: `en`, `en_UK`, `en_US`, `de`, `de_CH`.\n\nIf we need to support more regional differences within a country, then the\n[IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) might be a solution. This would even\nsupport the various Swiss German dialects!\n", "additionalProperties": {"type": "string"}}, "IconIdentifier": {"type": "string", "format": "^[a-z][a-z0-9]+:[a-zA-Z0-9\\-_\\.]+$", "maxLength": 255, "description": "Optional icon identifier. The identifier consists of a prefix and a resource identifier, separated by `:`.  \nAvailable prefixes:\n- `uc:` - integrated icon font \n- `custom:` - custom icon resource\n- `ctv:` - custom TV icon resource\n\nOther prefixes might be rejected by the service.\n\nAn empty identifier, while updating the object, removes the existing icon.\n"}, "ExternalSystemInfo": {"description": "Information about an external system.\n- The `token_id` field is only returned for `token_type: OAUTH2_APP`.\n- The `intg_driver_id` and `intg_name` fields are only returned if the system is associated with an integration driver.\n", "type": "object", "properties": {"system": {"$ref": "#/components/schemas/ExternalSystemId"}, "name": {"$ref": "#/components/schemas/ExtSystemName"}, "token_count": {"description": "Number of tokens associated with this external system.\nThe count reflects the requested token type, or the overall token count if no token type is specified.\n", "type": "integer"}, "token_id": {"$ref": "#/components/schemas/TokenId"}, "intg_driver_id": {"$ref": "#/components/schemas/DriverId"}, "intg_name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}}, "required": ["system", "name"]}, "ExternalSystemInfos": {"type": "array", "items": {"$ref": "#/components/schemas/ExternalSystemInfo"}}, "ExtAccessTokenDescription": {"type": "string", "maxLength": 2048, "description": "Optional description of the external access token."}, "ExtAccessTokenUrl": {"type": "string", "maxLength": 2048, "description": "Optional URL of the external system."}, "ExtAccessTokenData": {"type": "string", "maxLength": 32768, "description": "Optional data from the external system for the Remote integration.  \n\u26a0\ufe0f Attention: this data is not protected and retrievable by API clients!\n"}, "ExternalAccessToken": {"type": "object", "properties": {"system": {"$ref": "#/components/schemas/ExternalSystemId"}, "token_id": {"$ref": "#/components/schemas/TokenId"}, "token_type": {"$ref": "#/components/schemas/ExtTokenType"}, "name": {"$ref": "#/components/schemas/ExtSystemName"}, "description": {"$ref": "#/components/schemas/ExtAccessTokenDescription"}, "url": {"$ref": "#/components/schemas/ExtAccessTokenUrl"}, "data": {"$ref": "#/components/schemas/ExtAccessTokenData"}, "creation_date": {"type": "string", "format": "date-time"}}, "required": ["system", "token_id", "token_type", "name", "creation_date"]}, "ExternalAccessTokens": {"type": "array", "items": {"$ref": "#/components/schemas/ExternalAccessToken"}}, "ExtAccessToken": {"type": "string", "minLength": 1, "maxLength": 32768, "description": "The token to access the external system with the corresponding Remote integration.\nThis could be a UUID, a JWT, a PEM certificate or any other representation required for the integration to\nauthenticate on the system.\n"}, "ExternalAccessTokenRequest": {"type": "object", "description": "- The `token_type` is set to `TOKEN` if not provided.\n- For `token_type: OAUTH2_APP`, the `token_id` field is required and corresponds to the OAuth client ID.\n- For `token_type: TOKEN`, the `token_id` is optional and can be provided by the external system.\n  - If omitted, an UUID is generated and returned in the `ExternalAccessToken` response.\n  - The `token_id` may not end in `-DATA` or `-URL`.\n", "properties": {"token_type": {"$ref": "#/components/schemas/ExtTokenType"}, "token_id": {"$ref": "#/components/schemas/TokenId"}, "name": {"$ref": "#/components/schemas/ExtSystemName"}, "token": {"$ref": "#/components/schemas/ExtAccessToken"}, "description": {"$ref": "#/components/schemas/ExtAccessTokenDescription"}, "url": {"$ref": "#/components/schemas/ExtAccessTokenUrl"}, "data": {"$ref": "#/components/schemas/ExtAccessTokenData"}}, "required": ["name", "token"], "examples": [{"token_id": "1-2-3", "name": "My smart home", "token": "secret-sauce-42!", "description": "Any other informative message about the external system", "url": "ws://smart.home", "data": "optional: true, foo: bar, free: text"}]}, "ExternalAccessTokenResponse": {"type": "object", "description": "If the token identifier has been provided in the request, then then same identifier is returned, otherwise a\nUUID is generated.\n", "properties": {"token_id": {"$ref": "#/components/schemas/TokenId"}}, "required": ["token_id"]}, "AccessTokenId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 36, "description": "Unique token identifier. Usually a UUID."}, "ResourceType": {"type": "string", "format": "^[a-zA-Z]+$", "minLength": 1, "maxLength": 32}, "SupportedResource": {"type": "object", "properties": {"type": {"$ref": "#/components/schemas/ResourceType"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "file_formats": {"description": "Allowed file format extensions, e.g. `png`.", "type": "array", "items": {"type": "string"}}, "max_file_size": {"description": "Maximum file size in bytes.", "type": "integer"}, "max_count": {"description": "Maximum number of custom resources.", "type": "integer"}, "image": {"description": "Image specific restrictions. Only set for image resources.", "type": "object", "properties": {"sizes": {"description": "Allowed image sizes.", "type": "array", "items": {"type": "object", "properties": {"width": {"type": "integer"}, "height": {"type": "integer"}}, "required": ["width", "height"]}}}, "required": ["sizes"]}, "sound": {"type": "object", "description": "Sound file specific restrictions. Only set for sound resources.", "properties": {"bits": {"type": "array", "items": {"type": "integer"}}, "channels": {"type": "array", "items": {"type": "integer"}}, "sampling_rates": {"type": "array", "items": {"type": "integer"}}}}}, "required": ["type", "name", "file_formats", "max_file_size", "max_count"]}, "SupportedResources": {"type": "array", "items": {"$ref": "#/components/schemas/SupportedResource"}}, "ResourceItem": {"type": "object", "properties": {"type": {"$ref": "#/components/schemas/ResourceType"}, "id": {"type": "string", "description": "Resource identifier (normalized filename)"}, "size": {"type": "integer", "format": "int32", "description": "Size in bytes"}}}, "ResourceItems": {"type": "array", "items": {"$ref": "#/components/schemas/ResourceItem"}}, "IntegrationId": {"type": "string", "format": "^[a-zA-Z0-9\\-_\\.]+$", "minLength": 1, "maxLength": 73, "description": "Unique integration instance identifier. Automatically created by the system when creating a new instance from a driver.\n"}, "IntegrationDriverType": {"type": "string", "description": "- `LOCAL`: pre-installed integration driver in the firmware.\n- `CUSTOM`: user-installed custom integration driver on the remote.\n- `EXTERNAL`: external integration driver on the network.\n", "enum": ["LOCAL", "CUSTOM", "EXTERNAL"]}, "IntegrationState": {"type": "string", "enum": ["NOT_CONFIGURED", "UNKNOWN", "IDLE", "CONNECTING", "CONNECTED", "DISCONNECTED", "RECONNECTING", "ACTIVE", "ERROR"]}, "IntegrationStatus": {"type": "object", "description": "Integration status information. Intended to be used in a general overview of the integration drivers and instances.\n", "properties": {"driver_id": {"$ref": "#/components/schemas/DriverId"}, "integration_id": {"$ref": "#/components/schemas/IntegrationId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "driver_type": {"$ref": "#/components/schemas/IntegrationDriverType"}, "state": {"$ref": "#/components/schemas/IntegrationState"}}, "required": ["name", "driver_type"]}, "IntegrationDiscovery": {"type": "object", "properties": {"id": {"$ref": "#/components/schemas/DriverId"}, "configured": {"description": "Integration configuration flag:\n- true: driver has already been configured\n- false: driver has not yet been configured\n", "type": "boolean"}, "name": {"type": "string"}, "developer_name": {"type": "string"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "driver_url": {"description": "Resolved driver url.", "type": "string"}, "pwd_protected": {"description": "Driver requires a connection password.", "type": "boolean"}, "version": {"description": "Detected driver version.", "type": "string"}, "timestamp": {"description": "Timestamp of integration discovery.", "type": "string", "format": "date-time"}}, "required": ["id", "configured", "name", "driver_url"]}, "IntegrationDiscoveryStatus": {"type": "object", "properties": {"active": {"description": "Integration discovery still active or not.\n", "type": "boolean"}, "integrations": {"type": "array", "items": {"$ref": "#/components/schemas/IntegrationDiscovery"}}}, "required": ["active", "integrations"]}, "IntgAuthMethod": {"type": "string", "description": "Integration driver authentication method if a token is required.\n\nThe JSON `auth` message is used if a token is configured but no authentication method is set.\n", "enum": ["HEADER", "MESSAGE"]}, "DriverDeveloper": {"type": "object", "description": "Optional information about the integration developer.", "properties": {"name": {"description": "Optional developer information to display in UI / web-configurator.", "type": "string", "maxLength": 100}, "url": {"description": "Optional developer home page.", "type": "string", "format": "uri", "maxLength": 255}, "email": {"description": "Optional developer contact email.", "type": "string", "format": "email", "maxLength": 100}}}, "SettingTypeNumber": {"description": "Number input with optional `min`, `max`, `steps` and `decimals` properties. The default value must be specified\nin `value`. An optional unit of the number setting can be specified in `unit`, which will be displayed next to\nthe input field.\n", "type": "object", "properties": {"number": {"type": "object", "properties": {"value": {"description": "Default value for input field.", "type": "number"}, "min": {"description": "Optional validation: minimum allowed value (inclusive).", "type": "number"}, "max": {"description": "Optional validation: maximum allowed value (inclusive).", "type": "number"}, "steps": {"description": "Optional validation: allowed step increment between values. Might also be used in the UI for input helpers.\n", "type": "number"}, "decimals": {"description": "Number of decimal places. 0 = integer value", "type": "integer", "minimum": 0, "default": 0}, "unit": {"$ref": "#/components/schemas/LanguageText"}}, "required": ["value"]}}, "required": ["number"]}, "SettingTypeText": {"description": "Single line of text input.\n\nTODO: format specifier for e.g. email, url, date, datetime etc.?\n", "type": "object", "properties": {"text": {"type": "object", "properties": {"value": {"description": "Optional default value.", "type": "string"}, "regex": {"description": "Optional regex validation pattern for the input value.", "type": "string"}}}}, "required": ["text"]}, "SettingTypeTextArea": {"description": "Multi-line text input, e.g. for providing a description.", "type": "object", "properties": {"textarea": {"type": "object", "properties": {"value": {"description": "Optional default value.", "type": "string"}}}}, "required": ["textarea"]}, "SettingTypePassword": {"description": "Password or pin entry field with the input text hidden from the user. Otherwise the same as text input.\n", "type": "object", "properties": {"password": {"type": "object", "properties": {"value": {"description": "Optional default value.", "type": "string", "format": "password"}, "regex": {"description": "Optional regex validation pattern for the input value.", "type": "string"}}}}, "required": ["password"]}, "SettingTypeCheckbox": {"description": "Checkbox setting with `true` / `false` values.", "type": "object", "properties": {"checkbox": {"type": "object", "properties": {"value": {"description": "Initial setting.", "type": "boolean"}}, "required": ["value"]}}, "required": ["checkbox"]}, "SettingTypeDropdown": {"description": "Dropdown setting to pick a single value from a list. All values must be strings.", "type": "object", "properties": {"dropdown": {"type": "object", "properties": {"value": {"description": "Pre-selected dropdown id", "type": "string"}, "items": {"type": "array", "items": {"type": "object", "properties": {"id": {"description": "Selection identifier.", "type": "string"}, "label": {"$ref": "#/components/schemas/LanguageText"}}, "required": ["id", "label"]}}}, "required": ["items"]}}, "required": ["dropdown"]}, "SettingTypeLabel": {"description": "Additional read-only text for information purpose between other settings. Supports Markdown formatting.\n", "type": "object", "properties": {"label": {"type": "object", "properties": {"value": {"$ref": "#/components/schemas/LanguageText"}}, "required": ["value"]}}, "required": ["label"]}, "Setting": {"description": "An input setting is of a specific type defined in `field.type` which defines how it is presented to the user.\n\nInspired by the [Homey SDK settings](https://apps.developer.homey.app/the-basics/devices/settings) concept.\n", "type": "object", "properties": {"id": {"description": "Unique identifier of the setting to be returned with the entered value.", "type": "string", "maximum": 50}, "label": {"$ref": "#/components/schemas/LanguageText"}, "field": {"oneOf": [{"$ref": "#/components/schemas/SettingTypeNumber"}, {"$ref": "#/components/schemas/SettingTypeText"}, {"$ref": "#/components/schemas/SettingTypeTextArea"}, {"$ref": "#/components/schemas/SettingTypePassword"}, {"$ref": "#/components/schemas/SettingTypeCheckbox"}, {"$ref": "#/components/schemas/SettingTypeDropdown"}, {"$ref": "#/components/schemas/SettingTypeLabel"}]}}, "required": ["id", "label", "field"]}, "SettingsPage": {"description": "Settings definition page, e.g. to configure an integration driver.", "type": "object", "properties": {"title": {"$ref": "#/components/schemas/LanguageText"}, "settings": {"description": "One or multiple input field definitions, with optional pre-set values.", "type": "array", "items": {"$ref": "#/components/schemas/Setting"}}}, "required": ["title", "settings"]}, "DriverState": {"type": "string", "enum": ["NOT_CONFIGURED", "IDLE", "CONNECTING", "ACTIVE", "RECONNECTING", "ERROR"]}, "IntegrationDriver": {"type": "object", "description": "Integration driver model.\n\nA driver represents the communication aspect of an integration. E.g. how one can connect to it\nand which API version it supports.\n\nOne driver can provide multiple `Integration` instances. In the integration API they are\nreferred to as `multi-device integrations` and use the optional `device_id` property where\nrequired. If a driver only provides a single instance, which is usually the default use case,\nthen the `device_id` is not used (or set to the default value `main`).\n", "properties": {"driver_id": {"$ref": "#/components/schemas/DriverId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "driver_type": {"$ref": "#/components/schemas/IntegrationDriverType"}, "driver_url": {"description": "WebSocket URL of the driver. Only optional for integration driver metadata.", "type": "string", "format": "uri", "maxLength": 2048}, "token": {"description": "Optional driver authentication token.\n\nNote: the token will not be returned to external clients!\n", "type": "string", "maxLength": 2048}, "auth_method": {"$ref": "#/components/schemas/IntgAuthMethod"}, "pwd_protected": {"description": "Driver requires a connection password.", "type": "boolean"}, "version": {"description": "Driver version, [SemVer](https://semver.org/) preferred.", "type": "string", "maxLength": 20}, "min_core_api": {"description": "Optional version check: minimum required core API version in the remote.\n", "type": "string", "maxLength": 20}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "enabled": {"description": "Enables or disables driver communication. For development use only!  \nIf disabled, all integration instances won't be activated, even if the instance is enabled.\n", "type": "boolean"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "developer": {"$ref": "#/components/schemas/DriverDeveloper"}, "home_page": {"description": "Optional home page url for more information.", "type": "string", "format": "uri", "maxLength": 255}, "device_discovery": {"description": "Driver supports multi-device discovery. **Not yet supported**.", "type": "boolean"}, "setup_data_schema": {"$ref": "#/components/schemas/SettingsPage"}, "release_date": {"description": "Release date of the driver.", "type": "string", "format": "date"}, "driver_state": {"$ref": "#/components/schemas/DriverState"}}, "required": ["driver_id", "name", "version"]}, "IntegrationDriverInfo": {"type": "object", "description": "Summary data of an integration driver intended for overview screens.\n", "properties": {"driver_id": {"$ref": "#/components/schemas/DriverId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "developer_name": {"type": "string"}, "driver_type": {"$ref": "#/components/schemas/IntegrationDriverType"}, "driver_url": {"description": "WebSocket URL of external driver", "type": "string", "format": "uri", "maxLength": 255}, "version": {"type": "string"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "enabled": {"type": "boolean"}, "driver_state": {"$ref": "#/components/schemas/DriverState"}}, "required": ["driver_id", "name", "driver_type", "version", "enabled"]}, "SettingsValues": {"description": "User input result of a SettingsPage as key values.\n- key: id of the field\n- value: entered user value as string. This is either the entered text or number, selected checkbox state or the\n  selected dropdown item id.  \n  \u26a0\ufe0f Non native string values as numbers or booleans are represented as string values!\n", "type": "object", "additionalProperties": {"type": "string"}}, "CreateIntegrationSetup": {"type": "object", "properties": {"driver_id": {"$ref": "#/components/schemas/DriverId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "setup_data": {"$ref": "#/components/schemas/SettingsValues"}, "reconfigure": {"description": "Reconfigure an already configured integration.", "type": "boolean"}}, "required": ["driver_id"]}, "IntegrationSetupState": {"type": "string", "enum": ["SETUP", "WAIT_USER_ACTION", "OK", "ERROR"]}, "IntegrationSetupError": {"type": "string", "enum": ["NONE", "NOT_FOUND", "CONNECTION_REFUSED", "AUTHORIZATION_ERROR", "TIMEOUT", "OTHER"]}, "ConfirmationPage": {"description": "Confirmation screen.\n- `message1`: Message to display between title and image (if supplied). Supports Markdown formatting.\n- `message2`: Message to display below message1 or image (if supplied). Supports Markdown formatting.\n", "type": "object", "properties": {"title": {"$ref": "#/components/schemas/LanguageText"}, "message1": {"$ref": "#/components/schemas/LanguageText"}, "image": {"description": "Optional base64-encoded image.\n\nTODO maximum encoded length to avoid WebSocket continuation frames, supported image formats\n(png & svg?), max height & width\n", "type": "string", "format": "byte", "maxLength": 32768}, "message2": {"$ref": "#/components/schemas/LanguageText"}}, "required": ["title"]}, "IntegrationSetupInfo": {"type": "object", "description": "Integration setup state", "properties": {"id": {"type": "string"}, "state": {"$ref": "#/components/schemas/IntegrationSetupState"}, "error": {"$ref": "#/components/schemas/IntegrationSetupError"}, "require_user_action": {"description": "If set, the setup process waits for the specified user action.", "oneOf": [{"type": "object", "properties": {"input": {"$ref": "#/components/schemas/SettingsPage"}}, "required": ["input"]}, {"type": "object", "properties": {"confirmation": {"$ref": "#/components/schemas/ConfirmationPage"}}, "required": ["confirmation"]}]}}, "required": ["id", "state"]}, "IntegrationDrivers": {"type": "array", "items": {"$ref": "#/components/schemas/IntegrationDriverInfo"}}, "IntegrationDriverRequest": {"type": "object", "description": "Integration driver creation model. \n\n- The only required property is `driver_url` to contact the driver and fetch all driver data.\n- If the driver requires an access token, the `token` needs to be specified and optionally the authentication method\n  in `auth_method`.\n- The `driver_id` identifier can be specified by the client, but it needs to be unique among\n  all drivers. If omitted, the driver identifier returned by the driver will be used.  \n  A manually assigned, short, human-readable identifier is recommended for better recognizability.\n", "properties": {"driver_id": {"$ref": "#/components/schemas/DriverId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "driver_url": {"description": "WebSocket URL of the driver", "type": "string", "format": "uri", "maxLength": 2048}, "token": {"description": "Optional driver authentication token.", "type": "string", "maxLength": 2048}, "auth_method": {"$ref": "#/components/schemas/IntgAuthMethod"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "enabled": {"description": "Enables or disables driver communication. For development use only!  \nIf disabled, all integration instances won't be activated, even if the instance is enabled.\n", "type": "boolean"}}, "required": ["driver_url"]}, "DeviceId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 36, "description": "Device identifier for multi-device integrations only."}, "IntegrationUpdate": {"type": "object", "description": "Integration instance update model. This model corresponds to the `Integration` model except there are no required\nproperties to allow patch updates. \n\n- Specified properties will update the current values.\n- An empty value will delete a set property.\n- `device_id` is only required for multi-device integrations.\n", "properties": {"device_id": {"$ref": "#/components/schemas/DeviceId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "enabled": {"description": "Enable / disable flag. For development use only!", "type": "boolean"}, "setup_data": {"description": "Instance configuration object.", "type": "object"}}}, "DeviceState": {"type": "string", "enum": ["UNKNOWN", "CONNECTING", "CONNECTED", "DISCONNECTED", "ERROR"]}, "Integration": {"type": "object", "description": "Integration instance model.\n", "properties": {"integration_id": {"$ref": "#/components/schemas/IntegrationId"}, "driver_id": {"$ref": "#/components/schemas/DriverId"}, "device_id": {"$ref": "#/components/schemas/DeviceId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "enabled": {"description": "Enable / disable flag. For development use only!", "type": "boolean"}, "setup_data": {"description": "Instance configuration object", "type": "object"}, "device_state": {"$ref": "#/components/schemas/DeviceState"}}, "required": ["integration_id", "driver_id", "name", "enabled"]}, "IntegrationDriverUpdate": {"type": "object", "description": "Integration driver update model. This model corresponds to the `IntegrationDriverRequest` model except there are\nno required properties to allow patch updates. \n\n- Specified properties will update the current values.\n- An empty value will delete the currently set property.\n", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "driver_url": {"description": "WebSocket URL of the driver", "type": "string", "format": "uri", "maxLength": 2048}, "token": {"description": "Optional driver authentication token.", "type": "string", "maxLength": 2048}, "auth_method": {"$ref": "#/components/schemas/IntgAuthMethod"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "enabled": {"description": "Enables or disables driver communication.  \nIf disabled, all integration instances won't be activated, even if the instance is enabled.\n", "type": "boolean"}}}, "Integrations": {"type": "array", "items": {"$ref": "#/components/schemas/Integration"}}, "AvailableEntityId": {"type": "string", "format": "^[a-zA-Z0-9\\-_\\.]+$", "minLength": 1, "maxLength": 36, "description": "Entity identifier used in an integration driver (= available entities).\n"}, "EntityType": {"type": "string", "description": "Entity type", "enum": ["button", "climate", "cover", "light", "media_player", "sensor", "switch", "activity", "macro", "remote", "ir_emitter", "select", "voice_assistant"]}, "AvailableEntity": {"description": "Provided entity from an integration which can be configured to be used in the remote.\n\nSee [entity documentation](https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/)\nfor more information.\n\nIf no icon identifier is specified, the default icon for the entity type is used.\n", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/AvailableEntityId"}, "entity_type": {"$ref": "#/components/schemas/EntityType"}, "integration_id": {"$ref": "#/components/schemas/IntegrationId"}, "device_id": {"$ref": "#/components/schemas/DeviceId"}, "device_class": {"description": "Optional device type. This can be used by the UI to represent the entity with a different\nicon, behaviour etc. See entity documentation for available device classes.\n", "type": "string"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "features": {"description": "Supported features of the entity. See entity documentation for available features.\n", "type": "array", "items": {"type": "string"}}, "options": {"description": "Feature options. See entity documentation for available options.\n", "type": "object"}, "area": {"description": "Optional area if supported by the integration. E.g. `Living room`.", "type": "string"}}, "required": ["entity_id", "entity_type", "integration_id", "name", "features"]}, "EntityId": {"type": "string", "format": "^[a-zA-Z0-9\\-_\\.]+$", "minLength": 5, "maxLength": 110, "description": "Unique UC Remote identifier over all entities and integrations."}, "EntityUpdateRequest": {"type": "object", "description": "Update model for an entity.\n\n- Specified properties will update the current values.\n- An empty value will delete the currently set property.\n", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}}}, "Entity": {"description": "Configured entity in the remote to be used in one or more user profiles.\n\nSee [entity documentation](https://github.com/unfoldedcircle/core-api/blob/main/doc/entities/)\nfor more information.\n", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "entity_type": {"$ref": "#/components/schemas/EntityType"}, "integration_id": {"$ref": "#/components/schemas/IntegrationId"}, "device_class": {"description": "Optional device type. This can be used by the UI to represent the entity with a different\nicon, behaviour etc. See entity documentation for available device classes.\n", "type": "string"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "features": {"description": "Supported features of the entity. See entity documentation for available features.\n", "type": "array", "items": {"type": "string"}}, "options": {"description": "Feature options. See entity documentation for available options.\n", "type": "object"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "attributes": {"description": "Dynamic entity attributes set by the integration driver. These are key/value pairs, see [integration entity\ndocumentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities) for detailed information.\n", "type": "object"}}, "required": ["entity_id", "entity_type", "integration_id", "name"]}, "Entities": {"type": "array", "items": {"$ref": "#/components/schemas/Entity"}}, "EntityDeleteRequest": {"type": "object", "description": "Delete request model for multiple entities. Either specify `integration_id` or `entity_ids`.\n", "properties": {"integration_id": {"type": "string"}, "entity_ids": {"type": "array", "items": {"type": "string"}}}}, "EntityCommand": {"description": "Entity command object. The `entity_id` only has to be specified if it's not already included as a parameter in the URL.\n", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "cmd_id": {"description": "Entity command identifier, as returned in the entity command metadata.\n\nThis identifier may change at any time and may not be used for logic decisions in a client!\nIf entity specific information is required, the entity object must be loaded from the `entity_id`.\n", "type": "string"}, "params": {"description": "Optional command parameters as key / value pairs. See entity documentation for available parameters.\n", "type": "object"}}, "required": ["cmd_id"], "examples": [{"entity_id": "hass.main.light.living-room", "cmd_id": "light.on", "params": {"hue": 180, "saturation": 90}}]}, "MediaClass": {"description": "The media class is for browser/structure semantics.\nIt represents how a media item should be presented and organized in the media browser hierarchy.\n\n- Common values are defined as enum variants. Using these values is recommended, so the UI can show media type\n  specific information like icons. \n- Integrations can use their custom values. Short identifiers like URIs are recommended.\n", "type": "string", "maxLength": 255, "anyOf": [{"enum": ["album", "app", "artist", "channel", "composer", "directory", "episode", "game", "genre", "image", "movie", "music", "playlist", "podcast", "radio", "season", "track", "tv_show", "url", "video"]}, {}]}, "MediaContentType": {"description": "The media content type is for playback/content semantics.\nIt represents the type of the media content to play or that is currently playing.\n\nNotes:\n- Common values are defined as enum variants. Using these values is recommended, so the UI can show media type\n  specific information like icons. \n- Integrations can use their custom values. Short identifiers like URIs are recommended.\n", "type": "string", "maxLength": 255, "anyOf": [{"enum": ["album", "app", "apps", "artist", "channel", "channels", "composer", "episode", "game", "genre", "image", "movie", "music", "playlist", "podcast", "radio", "season", "track", "tv_show", "url", "video"]}, {}]}, "BrowseMediaItem": {"type": "object", "properties": {"media_id": {"description": "Unique identifier of the media item. Integration dependent.\nUse an empty value only for special non-playable media items, for example, a root directory in a media library or search result.\n", "type": "string", "maxLength": 255}, "title": {"description": "Display name.", "type": "string", "minLength": 1, "maxLength": 255}, "subtitle": {"description": "Optional subtitle.", "type": "string", "minLength": 1, "maxLength": 255}, "artist": {"description": "Optional artist name.", "type": "string", "minLength": 1, "maxLength": 255}, "album": {"description": "Optional album name.", "type": "string", "minLength": 1, "maxLength": 255}, "media_class": {"$ref": "#/components/schemas/MediaClass"}, "media_type": {"$ref": "#/components/schemas/MediaContentType"}, "can_browse": {"description": "If `true`, the item can be browsed (is a container) by using `media_id` and `media_type`.", "type": "boolean", "default": false}, "can_play": {"description": "If `true`, the item can be played directly using the `play_media` command with `media_id` and `media_type`.\n", "type": "boolean", "default": false}, "can_search": {"description": "If `true`, a search can be performed on the item using `search_media` with `media_id` and `media_type`.\n", "type": "boolean", "default": false}, "thumbnail": {"description": "URL to download the media artwork, or a base64 encoded PNG or JPG image.\nThe preferred size is 480x480 pixels.\nUse the following URI prefix to use a provided icon: `icon://uc:`, for example, `icon://uc:music`.\nPlease use a URL whenever possible. Encoded images should be as small as possible.\n", "type": "string", "minLength": 1, "maxLength": 32768}, "duration": {"description": "Duration in seconds.", "type": "integer"}, "items": {"description": "Child items if this item is a container. Child items may not contain further child items (only one level\nof nesting is supported). A new browse request must be sent for deeper levels.\n", "type": "array", "items": {"$ref": "#/components/schemas/BrowseMediaItem"}}}, "required": ["media_id", "title"]}, "MediaBrowseResponse": {"type": "object", "properties": {"media": {"$ref": "#/components/schemas/BrowseMediaItem"}}}, "SearchMediaItem": {"description": "A media item that was found by a search. Currently identical in shape to `BrowseMediaItem`.\nDefined as a composition to allow search-specific fields (e.g. relevance score) to be added in the future\nwithout a breaking change.\n\nA search media item may not contain any child `items`.\n", "allOf": [{"$ref": "#/components/schemas/BrowseMediaItem"}]}, "MediaSearchResponse": {"type": "array", "items": {"$ref": "#/components/schemas/SearchMediaItem"}}, "SimpleId": {"type": "string", "format": "^[a-zA-Z0-9\\-_\\.]+$", "minLength": 1, "maxLength": 36, "description": "Simple string identifier, also usable as URL parameter or file identifier"}, "ActivityFeature": {"description": "Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off`\nfeature, otherwise only `start`.\n", "type": "string", "enum": ["on_off", "start"]}, "ActivityOverview": {"description": "The activity entity executes a sequence of commands and at the end displays a user interface (similar to remote entity)\nto the user. If the entity has an off sequence, it can be turned off.\n", "type": "object", "allOf": [{"$ref": "#/components/schemas/Entity"}, {"properties": {"entity_type": {"type": "string", "enum": ["activity"]}, "features": {"description": "Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off`\nfeature, otherwise only `start`.\n", "type": "array", "items": {"$ref": "#/components/schemas/ActivityFeature"}}, "options": {"type": "object", "properties": {"editable": {"description": "- `true` / property missing: activity was created by UC Remote and can be edited.\n- `false`: activity was provided by an integration and cannot be edited.\n", "type": "boolean", "default": true}, "activity_group": {"$ref": "#/components/schemas/EntityId"}}}}}]}, "Activities": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityOverview"}}, "ActivityCreate": {"description": "Dedicated request object to create a new activity.\n", "type": "object", "allOf": [{"properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}}}, {"oneOf": [{"type": "object", "properties": {"clone_from": {"$ref": "#/components/schemas/EntityId"}}, "required": ["clone_from"]}, {"type": "object", "properties": {"clone_from": false, "options": {"type": "object", "properties": {"entity_ids": {"type": "array", "items": {"$ref": "#/components/schemas/EntityId"}}}, "required": ["entity_ids"]}}}]}], "required": ["name"]}, "ActivityGroupInfo": {"description": "Minimal activity group information to use in a user interface with it's friendly name and icon.\n", "type": "object", "properties": {"group_id": {"$ref": "#/components/schemas/EntityId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}}, "required": ["group_id", "name"]}, "TouchSliderTarget": {"description": "The target entity feature to control.", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "feature": {"description": "The feature to control. One of the listed entity features.\nThe default slider feature is controlled if not specified.\n", "type": "string"}}, "required": ["entity_id"]}, "TouchSliderUiCfg": {"description": "Remote 3 touch slider configuration. Assign the touch slider to a specific entity feature on a UI screen.\n\nIf no target is specified, the default slider feature is active, unless disabled with the `enabled` property.\n\n- `enabled: false`: disables the touch slider on the UI screen. Any `target` configuration is removed during update.\n- `enabled: true` and no `target`: the default slider feature is active on the UI screen.\n- `enabled: true` and `target`: the `target` entity feature is active on the UI screen.\n", "type": "object", "properties": {"enabled": {"description": "Enables or disables the touch slider. If set to false the slider is not active.\nThis affects the optional `target` configuration and the default slider feature.\n", "type": "boolean", "default": true}, "target": {"$ref": "#/components/schemas/TouchSliderTarget"}}, "required": ["enabled"]}, "VoiceAssistantTarget": {"description": "The specific voice assistant to use.", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "available": {"description": "Flag indicating if the referenced `entity_id` is still available or is a dangling reference.\n", "type": "boolean"}, "profile_id": {"$ref": "#/components/schemas/SimpleId"}}, "required": ["entity_id"]}, "VoiceAssistantUiCfg": {"description": "UI-specific voice assistant configuration. Overrides the global voice assistant.\n\n- The default voice assistant is used if no target is specified.\n- The voice assistant is activated with the voice button.\n- A custom voice button command mapping is ignored if a global or a UI-specific voice assistant is configured.\n", "type": "object", "properties": {"target": {"$ref": "#/components/schemas/VoiceAssistantTarget"}}}, "IncludedEntity": {"description": "When saving an activity only the `entity_id` is persisted. When retrieving an activity all other fields\nwill be retrieved from the real entities to make sure they are up to date. I.e. the entity name or icon\nmight change between saving an activity and retrieving it again!\n", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "entity_type": {"$ref": "#/components/schemas/EntityType"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "integration": {"description": "Optional integration information. Regular entities will have at least the integration name. Special\nentities like activities and macros might omit the integration object.\n", "type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}}}, "entity_commands": {"description": "Supported entity command identifiers. A command identifier refers to the common entity command\ndefinitions, which describe all required parameters to set for calling the entity command. This\nincludes the mandatory `cmd_id` attribute and optional parameters.\n", "type": "array", "items": {"type": "string"}}, "simple_commands": {"description": "Simple commands are additional commands supported by the entity, which are not included in the\ncommon entity command definitions. A typical example are remote-entity commands like `VOLUME_UP` etc\nwhich don't have additional parameters. A simple command relates directly to the `cmd_id` attribute\nwhen calling a command.\n", "type": "array", "items": {"type": "string"}}, "available": {"description": "State of the entity: True / missing = entity is available as configured entity and can be used.  \nFalse = entity has been removed and must be corrected by the user.\n\nIf an entity is no longer available then all usages in the sequences are still present in case the\nentity is re-configured. The execution of the on- or off-sequence will then simply skip the actions\nof the no longer available entity.\n", "type": "boolean"}}, "required": ["entity_id"]}, "IncludedEntities": {"description": "Included entities in an activity or macro. This object is writable from the client and persisted when saving.\n\nNotes:\n- Entities can be included without being used in a sequence.  \n  This allows to edit the activity or macro in multiple sessions without having to reselect the desired entities.\n- Every used entity in a sequence must be included, otherwise the activity or macro  cannot be saved.\n- If the client removes an entity which is included in an activity or macro, it must make sure to also remove all\n  entity references the sequence(s), button mapping and user interface.\n", "type": "array", "items": {"$ref": "#/components/schemas/IncludedEntity"}}, "CommandSequenceEntity": {"description": "Entity command step in a command sequence.", "type": "object", "properties": {"type": {"const": "command"}, "command": {"$ref": "#/components/schemas/EntityCommand"}}, "required": ["type", "command"], "examples": [{"type": "command", "command": {"entity_id": "hass.main.light.living-room", "cmd_id": "on", "params": {"brightness": 75}}}]}, "CommandSequenceDelay": {"description": "Delay step in a command sequence.", "type": "object", "properties": {"type": {"const": "delay"}, "delay": {"description": "Delay in milliseconds.", "type": "integer", "minimum": 1}}, "required": ["type", "delay"], "examples": [{"type": "delay", "delay": 100}]}, "CommandSequence": {"description": "Sequence of commands to execute.", "type": "array", "items": {"oneOf": [{"$ref": "#/components/schemas/CommandSequenceEntity"}, {"$ref": "#/components/schemas/CommandSequenceDelay"}], "discriminator": {"propertyName": "type", "mapping": {"command": "#/components/schemas/CommandSequenceEntity", "delay": "#/components/schemas/CommandSequenceDelay"}}}}, "ActivitySequences": {"type": "object", "properties": {"on": {"$ref": "#/components/schemas/CommandSequence"}, "off": {"$ref": "#/components/schemas/CommandSequence"}}}, "ButtonId": {"type": "string", "format": "^[A-Z0-9_]+$", "minLength": 1, "maxLength": 20, "description": "Physical button identification"}, "DeviceButtonMapping": {"type": "object", "properties": {"button": {"$ref": "#/components/schemas/ButtonId"}, "short_press": {"$ref": "#/components/schemas/EntityCommand"}, "long_press": {"$ref": "#/components/schemas/EntityCommand"}}, "required": ["button"]}, "DeviceButtonMappings": {"description": "Physical button mapping to entity commands. The `entity_id` in the EntityCommand object is a required\nproperty for an activity and ignored for a remote-entity.\n", "type": "array", "items": {"$ref": "#/components/schemas/DeviceButtonMapping"}}, "GridSize": {"description": "Grid layout size.", "type": "object", "properties": {"width": {"type": "integer", "minimum": 1}, "height": {"type": "integer", "minimum": 1}}, "required": ["width", "height"]}, "UserInterfaceItemType": {"description": "Type of the user interface item:\n- `icon`: show an icon, either a UC icon or a custom icon. Field `icon` must contain the icon identifier.\n- `text`: show text only from field `text`.\n- `media_player`: show media information from the specified media-player entity specified in `media_player_id`.  \n  The specified entity_id must be part of the included entities in the activity and of type media-player.\n- `select`: show a select box with the specified options from the select entity's `options` attribute.\n- `sensor`: show sensor value from the specified sensor entity specified in the `sensor` configuration object.\n", "type": "string", "enum": ["icon", "text", "numpad", "media_player", "select", "sensor"]}, "UserInterfaceItemSelect": {"description": "Select item configuration.\nBy default, only the selected option value in the `current_option` attribute is shown from the specified\nselect-entity.\nIf the user interface `text` field is set, it is used as a widget label, except if `show_name` is set to true.\nIf no widget label should be shown, omit the item's `text` field and set `show_name` to false.\n", "type": "object", "properties": {"select_id": {"$ref": "#/components/schemas/EntityId"}, "show_name": {"description": "Show the select-entity name as widget label instead of the user interface item's `text` field.", "type": "boolean", "default": false}}, "required": ["select_id"]}, "UserInterfaceItemSensor": {"description": "Sensor item configuration.\nBy default, only the sensor value and unit is shown from the specified sensor entity.\nIf the user interface `text` field is set, it is used as sensor label, except if `show_label` is set to true.\nIf no widget label should be shown, omit the item's `text` field and set `show_label` to false.\n", "type": "object", "properties": {"sensor_id": {"$ref": "#/components/schemas/EntityId"}, "show_label": {"description": "Show the sensor label instead of the user interface item's `text` field.", "type": "boolean", "default": false}, "show_unit": {"description": "Show sensor unit if available. Not shown for binary sensors.", "type": "boolean", "default": true}}, "required": ["sensor_id"]}, "GridLocation": {"description": "Button placement in the grid with 0-based coordinates.", "type": "object", "properties": {"x": {"type": "integer", "minimum": 0}, "y": {"type": "integer", "minimum": 0}}, "required": ["x", "y"]}, "GridItemSize": {"description": "Item size in the button grid. Default size if not specified: 1 x 1", "type": "object", "properties": {"width": {"type": "integer", "minimum": 1, "default": 1}, "height": {"type": "integer", "minimum": 1, "default": 1}}}, "UserInterfaceItem": {"description": "A user interface item is either an icon, text, sensor value or media information from a media-player entity.\n- Icon and text items can be static or linked to a command specified in the `command` field.\n- The command object can only be used for `icon` and `text` items.\n- Default size is 1x1 if not specified.\n", "type": "object", "properties": {"type": {"$ref": "#/components/schemas/UserInterfaceItemType"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "text": {"type": "string", "minLength": 1, "maxLength": 50}, "media_player_id": {"$ref": "#/components/schemas/EntityId"}, "select": {"$ref": "#/components/schemas/UserInterfaceItemSelect"}, "sensor": {"$ref": "#/components/schemas/UserInterfaceItemSensor"}, "command": {"$ref": "#/components/schemas/EntityCommand"}, "location": {"$ref": "#/components/schemas/GridLocation"}, "size": {"$ref": "#/components/schemas/GridItemSize"}}, "required": ["type", "location"]}, "ActivityUserInterfacePage": {"type": "object", "properties": {"page_id": {"$ref": "#/components/schemas/SimpleId"}, "name": {"description": "Optional page name", "type": "string"}, "grid": {"$ref": "#/components/schemas/GridSize"}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/UserInterfaceItem"}}}, "required": ["page_id", "grid", "items"]}, "ActivityUserInterface": {"type": "object", "properties": {"pages": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityUserInterfacePage"}}}}, "SequenceState": {"description": "State of an Activity or Macro sequence:\n- `RUNNING`: Sequence is currently running\n- `COMPLETED`: Final state for a macro\n- `ON`: Final activity state for the `on` sequence\n- `OFF`: Final activity state for the `off` sequence\n- `STOPPED`: The sequence was aborted with a stop request\n- `TIMEOUT`: The sequence timed out and was aborted\n- `ERROR`: There was an error running the sequence and did not complete\n", "type": "string", "enum": ["RUNNING", "COMPLETED", "ON", "OFF", "STOPPED", "TIMEOUT", "ERROR"]}, "Activity": {"description": "The activity entity executes a sequence of commands and at the end displays a user interface (similar to remote entity)\nto the user. If the entity has an off sequence, it can be turned off.\n", "type": "object", "allOf": [{"$ref": "#/components/schemas/Entity"}, {"properties": {"entity_type": {"type": "string", "enum": ["activity"]}, "features": {"description": "Supported features of the activity. If the activity has an `off` sequence, it supports the common `on_off`\nfeature, otherwise only `start`.\n", "type": "array", "items": {"$ref": "#/components/schemas/ActivityFeature"}}, "options": {"type": "object", "properties": {"editable": {"description": "- `true` / property missing: activity was created by UC Remote and can be edited.\n- `false`: activity was provided by an integration and cannot be edited.\n", "type": "boolean", "default": true}, "activity_group": {"$ref": "#/components/schemas/ActivityGroupInfo"}, "prevent_sleep": {"description": "Prevent the device to go to sleep while activity is on.", "type": "boolean"}, "ready_check": {"description": "Readiness check when turning the activity on or off.\nChecks if entities in the on- or off-sequence are available before running the sequence.\n", "type": "boolean", "default": true}, "touch_slider": {"$ref": "#/components/schemas/TouchSliderUiCfg"}, "voice_assistant": {"$ref": "#/components/schemas/VoiceAssistantUiCfg"}, "included_entities": {"$ref": "#/components/schemas/IncludedEntities"}, "sequences": {"$ref": "#/components/schemas/ActivitySequences"}, "button_mapping": {"$ref": "#/components/schemas/DeviceButtonMappings"}, "user_interface": {"$ref": "#/components/schemas/ActivityUserInterface"}}}, "attributes": {"type": "object", "properties": {"state": {"$ref": "#/components/schemas/SequenceState"}}}}, "required": ["options", "attributes"]}]}, "ActivityUpdate": {"description": "Dedicated request object to update an existing activity.  \nAll root properties are optional and only the provided objects are updated in the activity. Omitted objects are\nignored and not deleted from the activity.\n\nThe `entity_ids` object must be managed by the client and is persisted when updating an activity.\n\nNotes:\n- Entities can be included in `entity_ids` without being used in `sequences`.  \n  This allows to edit the activity in multiple sessions without having to reselect the desired entities.\n- Every referenced entity in `sequences` must be included in `entity_ids`, otherwise the activity cannot be saved.\n- If the client removes a configured entity from the system which is included in an activity, it must make sure to\n  also remove all references in the activity. See `IncludedEntity.available` property in the included entities\n  object when retrieving an activity.\n- Remote 3: The `touch_slider` configuration requires an entity included in `entity_ids`.\n", "type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "options": {"type": "object", "properties": {"prevent_sleep": {"description": "Prevent the device to go to sleep while activity is on.", "type": "boolean"}, "ready_check": {"description": "Readiness check when turning the activity on or off.\nChecks if entities in the on- or off-sequence are available before running the sequence.\n", "type": "boolean"}, "touch_slider": {"$ref": "#/components/schemas/TouchSliderUiCfg"}, "voice_assistant": {"$ref": "#/components/schemas/VoiceAssistantUiCfg"}, "entity_ids": {"type": "array", "items": {"$ref": "#/components/schemas/EntityId"}}, "sequences": {"$ref": "#/components/schemas/ActivitySequences"}}}}}, "ActivityUserInterfacePageUpdate": {"type": "object", "properties": {"name": {"description": "Optional page name", "type": "string"}, "grid": {"$ref": "#/components/schemas/GridSize"}, "items": {"description": "Updated user interface items. An empty array will REMOVE all items, if the property is omitted the existing\nconfiguration is not changed.\n", "type": "array", "items": {"$ref": "#/components/schemas/UserInterfaceItem"}}}}, "ActivityGroupState": {"description": "- `OFF`: No included activity is running.\n- `ACTIVE`: An included activity is running.\n- `RUNNING`: An included activity is currently running, e.g. either switching activities, or turning off.\n- `ERROR`: An included activity is in an error state.\n", "type": "string", "enum": ["OFF", "ACTIVE", "RUNNING", "ERROR"]}, "ActivityGroupOverview": {"description": "Minimal activity group object intended for an overview page, which is returned when retrieving all activity groups.\n", "type": "object", "properties": {"group_id": {"$ref": "#/components/schemas/EntityId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "activity_count": {"description": "Number of included activities.", "type": "integer"}, "state": {"$ref": "#/components/schemas/ActivityGroupState"}}, "required": ["group_id", "name", "activity_count"]}, "ActivityGroups": {"type": "array", "items": {"$ref": "#/components/schemas/ActivityGroupOverview"}}, "RemoveTurnOnDelays": {"description": "- `previous_cmd_skipped`: Only remove delay steps if the previous step is skipped, because the entity is in a\n   power-on state.\n- `between_skipped_cmds`: Only remove delay steps if the previous and next power-on steps are skipped, because\n   the entity is already in a power-on state.\n- `never`: Never remove delay steps in the on-sequence of the new activity.\n", "type": "string", "enum": ["previous_cmd_skipped", "between_skipped_cmds", "never"]}, "TurnOffUnusedEntities": {"description": "- `always`: Always turn off unused entities in the previous activity.  \n   All included entities are considered, not just the ones used in the on-sequence of the new activity.\n- `in_off_sequence`: Only turn off unused entities which are included in the off-sequence of the previous activity.\n- `run_off_sequence`: Run the original off-sequence of the old activity and dynamically filter out power-off commands.  \n   All power-off commands from entities used in the new activity's power-on sequence will be filtered out.\n- `never`: Never turn off entities in the previous activity.\n", "type": "string", "enum": ["always", "in_off_sequence", "run_off_sequence", "never"]}, "ActivityGroupOptions": {"description": "\ud83d\udc77Not yet finalized!\n\nActivity group specific options, e.g. how delays are handled when switching between activities.\n", "type": "object", "properties": {"remove_turn_on_delays": {"$ref": "#/components/schemas/RemoveTurnOnDelays"}, "turn_off_unused_entities": {"$ref": "#/components/schemas/TurnOffUnusedEntities"}}}, "ActivityGroupUpdate": {"description": "Dedicated request object to update an existing activity group.  \nAll root properties are optional and only the provided objects are updated in the activity group. Omitted objects are\nignored and not deleted from the activity group.\n\nReferenced activities must exist, an empty `activity_ids` array will remove all included activities from the group.\n", "type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "options": {"$ref": "#/components/schemas/ActivityGroupOptions"}, "activity_ids": {"description": "Entity identifiers of included activities in group.", "type": "array", "items": {"$ref": "#/components/schemas/EntityId"}}}}, "IncludedActivity": {"description": "Minimal activity object to show the activity in a user interface with it's friendly name and icon.\n", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "state": {"$ref": "#/components/schemas/SequenceState"}}, "required": ["entity_id", "name"]}, "ActivityGroup": {"description": "An activity group creates a dependency between multiple activities. Switching between activities will consider\nthe current state of the included entities and only turn-on or -off the required entities.\n", "type": "object", "properties": {"group_id": {"$ref": "#/components/schemas/EntityId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "options": {"$ref": "#/components/schemas/ActivityGroupOptions"}, "activities": {"description": "Included activities in the group.", "type": "array", "items": {"$ref": "#/components/schemas/IncludedActivity"}}}, "required": ["group_id", "name", "options", "activities"]}, "MacroFeature": {"type": "string", "enum": ["start"]}, "MacroOverview": {"description": "The macro entity executes a sequence of commands.\n", "type": "object", "allOf": [{"$ref": "#/components/schemas/Entity"}, {"properties": {"entity_type": {"type": "string", "enum": ["macro"]}, "features": {"description": "Supported features of the macro.\n", "type": "array", "items": {"$ref": "#/components/schemas/MacroFeature"}}, "options": {"type": "object", "properties": {"editable": {"description": "- `true` / property missing: macro was created by UC Remote and can be edited.\n- `false`: macro was provided by an integration and cannot be edited.\n", "type": "boolean", "default": true}}}}}]}, "Macros": {"type": "array", "items": {"$ref": "#/components/schemas/MacroOverview"}}, "MacroCreate": {"description": "Dedicated request object to create a new macro.\n", "type": "object", "allOf": [{"properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}}}, {"oneOf": [{"type": "object", "properties": {"clone_from": {"$ref": "#/components/schemas/EntityId"}}, "required": ["clone_from"]}, {"type": "object", "properties": {"clone_from": false, "options": {"type": "object", "properties": {"entity_ids": {"type": "array", "items": {"$ref": "#/components/schemas/EntityId"}}}, "required": ["entity_ids"]}}}]}], "required": ["name"]}, "Macro": {"description": "The macro entity executes a sequence of commands.\n", "type": "object", "allOf": [{"$ref": "#/components/schemas/Entity"}, {"properties": {"entity_type": {"type": "string", "enum": ["macro"]}, "features": {"description": "Supported features of the macro.\n", "type": "array", "items": {"$ref": "#/components/schemas/MacroFeature"}}, "options": {"type": "object", "properties": {"editable": {"description": "- `true` / property missing: macro was created by UC Remote and can be edited.\n- `false`: macro was provided by an integration and cannot be edited.\n", "type": "boolean", "default": true}, "included_entities": {"$ref": "#/components/schemas/IncludedEntities"}, "sequence": {"$ref": "#/components/schemas/CommandSequence"}}}}, "required": ["options"]}]}, "MacroUpdate": {"description": "Dedicated request object to update an existing macro.  \nAll root properties are optional and only the provided objects are updated in the macro. Omitted objects are\nignored and not deleted from the macro.\n\nThe `entity_ids` object must be managed by the client and is persisted when updating a macro.\n\nNotes:\n- Entities can be included in `entity_ids` without being used in `sequence`.  \n  This allows to edit the macro in multiple sessions without having to reselect the desired entities.\n- Every referenced entity in `sequence` must be included in `entity_ids`, otherwise the macro cannot be saved.\n- If the client removes a configured entity from the system which is included in a macro, it must make sure to also\n  remove all references in the macro. See `available` property in the included entities object when retrieving a macro.\n", "type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "options": {"type": "object", "properties": {"entity_ids": {"type": "array", "items": {"$ref": "#/components/schemas/EntityId"}}, "sequence": {"$ref": "#/components/schemas/CommandSequence"}}}}}, "CodeSetInfo": {"type": "object", "properties": {"manufacturer_id": {"type": "string"}, "manufacturer": {"type": "string"}, "device_id": {"type": "string"}, "device": {"type": "string"}, "device_type": {"type": "string"}}, "required": ["manufacturer_id", "manufacturer", "device_id", "device", "device_type"]}, "DeviceType": {"type": "string", "enum": ["audio", "radio", "cd_player", "receiver", "soundbar", "hdmi_switch", "television", "projector", "set_top_box", "media_player", "dvd_player", "bluray_player", "climate", "light", "various"]}, "IrCodeFormat": {"description": "Supported IR code formats:\n- `HEX`: Unfolded Circle HEX codes, `<protocol>;<hex-ir-code>;<bits>;<repeat-count>` (based on\n  [IRremoteESP8266 Hex](https://github.com/unfoldedcircle/IRremoteESP8266) format).\n  - protocol: numeric value from supported and enabled protocols. See: [decode_type_t](https://github.com/unfoldedcircle/IRremoteESP8266/blob/v2.8.5-ucd2.2/src/IRremoteESP8266.h#L1011)\n  - hex-ir-code: HEX value prefixed with `0x`\n  - bits: number of bits in hex value\n  - repeat-count: number of repeats\n- `PRONTO`: PRONTO hex codes\n  - Only raw codes are supported. First number must be `0000`.\n", "type": "string", "enum": ["HEX", "PRONTO"]}, "IrCodeKey": {"description": "IR command key identifier", "type": "string", "format": "^[a-zA-Z0-9\\-_\\.:+#*\u00b0@%/()?]{1,50}$"}, "IrCodeValue": {"description": "IR code value, either in HEX or PRONTO format as defined in the format field.\n\n- Multiple IR codes in a sequence can be specified with a plus character `+` as divider.\n  - For example: `3;0x20F0A956;32;0 + 3;0x20F02956;32;0`\n  - This works for HEX and PRONTO\n- PRONTO only: 2 toggling codes can be specified with a pipe character `|` as divider.\n  - Only two toggling codes are valid. \n  - For example: `0000 0068 0001 0000 0002 0800 | 0000 0068 0001 0000 8002 0800`\n- \u26a0\ufe0f Sequence and toggle divider cannot be mixed.\n", "type": "string", "format": "^(?:(?:\\d{1,3};0x[a-fA-F0-9]{1,16};\\d{1,2};\\d{1,2}(?:\\s*\\+\\s*\\d{1,3};0x[a-fA-F0-9]{1,16};\\d{1,2};\\d{1,2})*)|(?:0000(?:[, ][a-fA-F0-9]{4}){5,}(?:(?:\\s*\\+\\s*0000(?:[, ][a-fA-F0-9]{4}){5,})*|\\s*\\|\\s*0000(?:[, ][a-fA-F0-9]{4}){5,})))$"}, "IrCodeCreate": {"type": "object", "properties": {"key": {"$ref": "#/components/schemas/IrCodeKey"}, "value": {"$ref": "#/components/schemas/IrCodeValue"}}, "required": ["key", "value"]}, "CodeSetCreate": {"type": "object", "properties": {"manufacturer": {"description": "Optional manufacturer name. If not specified: the codeset will be linked to the custom manufacturer entry\nfor self learned codes.\n", "type": "string", "minLength": 1, "maxLength": 100}, "device": {"type": "string", "minLength": 1, "maxLength": 100}, "device_type": {"$ref": "#/components/schemas/DeviceType"}, "code_format": {"$ref": "#/components/schemas/IrCodeFormat"}, "codes": {"type": "array", "items": {"$ref": "#/components/schemas/IrCodeCreate"}}}, "required": ["device", "device_type"]}, "IrCode": {"type": "object", "properties": {"key": {"type": "string"}, "format": {"$ref": "#/components/schemas/IrCodeFormat"}, "value": {"type": "string"}}, "required": ["key", "format", "value"]}, "CodeSet": {"type": "object", "properties": {"manufacturer_id": {"type": "string"}, "manufacturer": {"type": "string"}, "device_id": {"type": "string"}, "device": {"type": "string"}, "device_type": {"type": "string"}, "codes": {"type": "array", "items": {"$ref": "#/components/schemas/IrCode"}}}, "required": ["manufacturer", "manufacturer_id", "device_id", "device", "device_type", "codes"]}, "CodeSetUploadResult": {"type": "object", "properties": {"processed": {"type": "integer"}, "added": {"type": "integer"}, "updated": {"type": "integer"}}}, "CodeSetUpdate": {"type": "object", "properties": {"device": {"type": "string", "minLength": 1, "maxLength": 100}, "device_type": {"$ref": "#/components/schemas/DeviceType"}}}, "IrCodeUpdate": {"type": "object", "properties": {"format": {"$ref": "#/components/schemas/IrCodeFormat"}, "value": {"$ref": "#/components/schemas/IrCodeValue"}}, "required": ["format", "value"]}, "IrRawCode": {"type": "object", "properties": {"raw": {"type": "array", "items": {"type": "integer", "minimum": 0}}, "frequency": {"type": "integer", "minimum": 0}, "duty_cycle": {"type": "integer", "minimum": 0, "maximum": 100}}, "required": ["raw", "frequency"]}, "IrEmitterType": {"type": "string", "description": "The type of the IR emitter device:\n- `DOCK`: an Unfolded Circle docking station\n- `INTERNAL`: internal IR\n- `IR_BLASTER`: a network based IR blaster\n- `OTHER`: something else\n", "enum": ["DOCK", "INTERNAL", "IR_BLASTER", "OTHER"]}, "IrEmitterLearningCapability": {"type": "object", "description": "Emitter can also be used for learning IR codes.", "properties": {"description": {"type": "string"}, "instruction": {"type": "string"}, "formats": {"type": "array", "items": {"type": "string"}}, "send_while_learn": {"description": "Emitter is able to send IR codes while in learn mode.", "type": "boolean", "default": false}}, "required": ["formats"]}, "IrEmitterPortMode": {"type": "string", "description": "Optional IR-emitter output port mode, default is `INFRARED`. Specifies what kind of output it is.\n- `NONE`: port is not active or disabled\n- `UNKNOWN`: output is not known, for example if auto-detection is active\n- `INFRARED`: generic infrared output\n- `IR_BLASTER`: IR-blaster output\n- `IR_EMITTER`: IR-emitter output\n- `OTHER`: port is not configured for infrared output \n", "enum": ["NONE", "UNKNOWN", "INFRARED", "IR_BLASTER", "IR_EMITTER", "OTHER"]}, "IrEmitterPortState": {"type": "string", "description": "Optional IR-emitter output port state, default is `ACTIVE`.\n- `ACTIVE`: IR output is enabled\n- `ERROR`: output is in error state\n- `DISABLED`: output is disabled\n- `OTHER`: output port is not configured for infrared \n", "enum": ["ACTIVE", "ERROR", "DISABLED", "OTHER"]}, "IrEmitterPort": {"description": "IR emitter output port definition. The optional `mode` and `state` fields can be used for dynamic output ports,\nif the port can be become unavailable, or re-configured to a non-infrared mode. This allows the UI to show more\ninformation in the port selection.\n", "type": "object", "properties": {"port_id": {"description": "IR emitter output port identifier.", "type": "string"}, "name": {"description": "Friendly name of the output port.", "type": "string"}, "mode": {"$ref": "#/components/schemas/IrEmitterPortMode"}, "state": {"$ref": "#/components/schemas/IrEmitterPortState"}}, "required": ["port_id", "name"]}, "IrEmitter": {"type": "object", "properties": {"device_id": {"description": "IR emitter device identifier.", "type": "string"}, "type": {"$ref": "#/components/schemas/IrEmitterType"}, "name": {"description": "Friendly name of the IR emitter device.", "type": "string"}, "active": {"description": "Emitter device is active or currently not available.", "type": "boolean"}, "capabilities": {"description": "Optional capabilities of the emitter.", "type": "object", "properties": {"learning": {"$ref": "#/components/schemas/IrEmitterLearningCapability"}}}, "ports": {"description": "Available output ports of the emitter.\nA simple emitter might only have one IR output, whereas the Remote Two dock has 4 individual outputs.\n", "type": "array", "items": {"$ref": "#/components/schemas/IrEmitterPort"}}}, "required": ["device_id", "type", "name", "active", "ports"]}, "IrEmitters": {"type": "array", "items": {"$ref": "#/components/schemas/IrEmitter"}}, "LearnedIrCode": {"type": "object", "properties": {"code": {"type": "string"}, "format": {"$ref": "#/components/schemas/IrCodeFormat"}, "timestamp": {"type": "string", "format": "date-time"}}}, "IrEmitterLearnStatus": {"type": "object", "properties": {"device_id": {"description": "IR emitter device identifier.", "type": "string"}, "learning_active": {"description": "Device is in IR learning mode. Usually an emitter can't send IR commands while it is in learning mode.\n", "type": "boolean"}, "codes": {"type": "array", "items": {"$ref": "#/components/schemas/LearnedIrCode"}}}, "required": ["device_id", "learning_active", "codes"]}, "RemoteKind": {"description": "Type of remote-entity:\n- `BT`: Bluetooth remote\n- `IR`: Infrared remote\n- `EXTERNAL`: Remote-entity provided from an integration to control a single device.\n", "type": "string", "enum": ["BT", "IR", "EXTERNAL"], "default": "IR"}, "RemoteFeature": {"type": "string", "enum": ["on_off", "send"]}, "RemoteOverview": {"type": "object", "allOf": [{"$ref": "#/components/schemas/Entity"}, {"properties": {"entity_type": {"type": "string", "enum": ["remote"]}, "features": {"description": "Supported features of the remote.\n", "type": "array", "items": {"$ref": "#/components/schemas/RemoteFeature"}}, "options": {"type": "object", "properties": {"editable": {"description": "- `true` / property missing: remote was created by UC Remote and can be edited.\n- `false`: remote was provided by an integration and cannot be edited.\n", "type": "boolean", "default": true}}}}}]}, "Remotes": {"type": "array", "items": {"$ref": "#/components/schemas/RemoteOverview"}}, "BtRemoteCreateOptions": {"description": "Options for creating a Bluetooth peripheral remote-entity.", "type": "object", "properties": {"dev_profile_id": {"description": "Bluetooth device profile identifier to customize available commands, button mappings and default UI screens.\n", "type": "string"}}}, "RemoteCreate": {"description": "Dedicated request object to create a new remote.\n", "type": "object", "allOf": [{"properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}}}, {"oneOf": [{"type": "object", "properties": {"clone_from": {"$ref": "#/components/schemas/EntityId"}}, "required": ["clone_from"]}, {"type": "object", "properties": {"codeset_id": {"$ref": "#/components/schemas/SimpleId"}}, "required": ["codeset_id"]}, {"type": "object", "properties": {"custom_codeset": {"type": "object", "properties": {"manufacturer_id": {"type": "string", "default": "custom"}, "device_name": {"type": "string"}, "device_type": {"$ref": "#/components/schemas/DeviceType"}}, "required": ["device_name"]}}, "required": ["custom_codeset"]}, {"type": "object", "properties": {"kind": {"$ref": "#/components/schemas/RemoteKind"}, "bt": {"$ref": "#/components/schemas/BtRemoteCreateOptions"}}, "required": ["kind", "bt"]}]}], "required": ["name"]}, "BtDevicePeripherals": {"description": "Supported device peripherals. A device can support a single mode or act as a composite device.", "type": "object", "properties": {"keyboard": {"description": "Device is a HID keyboard", "type": "boolean"}, "mouse": {"description": "Device is a mouse keyboard", "type": "boolean"}}}, "IrCodeSetType": {"description": "Type of codeset, either a manufacturer codeset or a custom codeset.", "type": "string", "enum": ["manufacturer", "custom"]}, "Remote": {"description": "The remote entity executes a sequence of commands and at the end displays a user interface (similar to remote entity)\nto the user. If the entity has an off sequence, it can be turned off.\n", "type": "object", "allOf": [{"$ref": "#/components/schemas/Entity"}, {"properties": {"entity_type": {"type": "string", "enum": ["remote"]}, "features": {"description": "Supported features of the remote. If the remote has an `off` sequence, it supports the common `on_off`\nfeature, otherwise only `start`.\n", "type": "array", "items": {"$ref": "#/components/schemas/RemoteFeature"}}, "options": {"type": "object", "properties": {"editable": {"description": "- `true` / property missing: remote was created by UC Remote and can be edited.\n- `false`: remote was provided by an integration and cannot be edited.\n", "type": "boolean", "default": true}, "kind": {"$ref": "#/components/schemas/RemoteKind"}, "bt": {"type": "object", "properties": {"dev_profile_id": {"description": "BT device profile identifier", "type": "string"}, "peripherals": {"$ref": "#/components/schemas/BtDevicePeripherals"}, "profile": {"description": "BT peripheral connection profile", "type": "integer"}}}, "ir": {"description": "Infrared settings: codeset name und used infrared emitter to send commands.\n", "type": "object", "properties": {"cmd_delay": {"description": "Delay in milliseconds between sending IR commands, if a command contains multiple IR codes.\n", "type": "integer", "minimum": 0}, "repeat": {"description": "Repeat each IR command in the dataset n times. Defaults to 0 (no repeat) if not specified.  \nThis setting is intended mainly for PRONTO codes with certain devices requiring the same command being\nsent twice (e.g. Sony and Epson devices).\n", "type": "integer", "minimum": 0, "maximum": 20}, "codeset": {"description": "Read-only information about the infrared codeset. \ud83d\udc77 **TODO** Use `/remotes/entities/:entityId/ir`\nendpoints to manage infrared codes.\n", "type": "object", "properties": {"id": {"description": "Codeset identifier, either a custom codeset id or a manufacturer codeset id depending on `type`.\n", "type": "string"}, "name": {"description": "User friendly name of the used codeset (custom or manufacturer) to show in a user interface.\n", "type": "string"}, "type": {"$ref": "#/components/schemas/IrCodeSetType"}}}, "output": {"description": "Infrared output device settings. Use `/ir/emitter` endpoints to retrieve further information.\n", "type": "object", "properties": {"device_id": {"description": "IR emitter device identifier.\n", "type": "string"}, "port_id": {"description": "IR emitter output port identifier.\n", "type": "string"}}}}}, "simple_commands": {"description": "All available commands of the infrared codeset for the button mapping and user interface.  \nThese simple commands relate directly to the `cmd_id` attribute when defining or calling an entity command.\n\nThe commands are read-only and updated automatically based on the infrared codeset.\n", "type": "array", "items": {"type": "string"}}, "button_mapping": {"$ref": "#/components/schemas/DeviceButtonMappings"}, "user_interface": {"$ref": "#/components/schemas/ActivityUserInterface"}}}}, "required": ["options"]}]}, "RemoteUpdate": {"description": "Dedicated request object to update an existing remote.  \nAll root properties are optional and only the provided objects are updated in the remote-entity. Omitted objects are\nignored and not deleted from the remote-entity.\n", "type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "options": {"type": "object", "properties": {"ir": {"type": "object", "properties": {"cmd_delay": {"description": "Delay in milliseconds between sending IR commands, if a command contains multiple IR codes.\n", "type": "integer", "minimum": 0}, "repeat": {"description": "Repeat each IR command in the dataset n times. Defaults to 0 (no repeat) if not specified.  \nThis setting is intended mainly for PRONTO codes with certain devices requiring the same command being\nsent twice (e.g. Sony and Epson devices).\n", "type": "integer", "minimum": 0, "maximum": 20}, "codeset": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}, "output": {"type": "object", "properties": {"device_id": {"type": "string"}, "port_id": {"type": "string"}}, "required": ["device_id", "port_id"]}}}}}}}, "RemoteIrCode": {"type": "object", "properties": {"cmd_id": {"$ref": "#/components/schemas/SimpleId"}, "code": {"description": "Custom infrared code. Only set for custom codeset or if a manufacturer codeset has been modified or enhanced.\n", "type": "object", "properties": {"value": {"type": "string"}, "format": {"$ref": "#/components/schemas/IrCodeFormat"}}}, "custom": {"description": "Flag indicating if this code is a custom code in a manufacturer codeset. This is a manually added code which\nwas not present in the codeset. Custom codes can be deleted or edited by the user. The modified code is\nstored in the `code` object.\n", "type": "boolean"}, "modified": {"description": "Flag indicating if a manufacturer code has been replaced with a user code. The modified code is stored in\nthe `code` object. Modified codes can be edited by the user.\n", "type": "boolean"}}, "required": ["cmd_id"]}, "RemoteIrDataSet": {"type": "object", "properties": {"id": {"description": "Codeset identifier, either a custom codeset id or a manufacturer codeset id depending on `type`.\n", "type": "string"}, "name": {"description": "User friendly name of the codeset (custom or manufacturer).", "type": "string"}, "type": {"$ref": "#/components/schemas/IrCodeSetType"}, "codes": {"type": "array", "items": {"$ref": "#/components/schemas/RemoteIrCode"}}}}, "BtAddressType": {"description": "Address type:\n- `LE_PUBLIC`: Public device address\n- `LE_RANDOM`: Random device address\n- `LE_PUBLIC_IDENTITY`: Public identity address (corresponds to resolved private address)\n- `LE_RANDOM_IDENTITY`: Random (static) identity address (corresponds to resolved private address)\n- `UNKNOWN`: Address could not be determined, or an error occurred\n", "type": "string", "enum": ["LE_PUBLIC", "LE_RANDOM", "LE_PUBLIC_IDENTITY", "LE_RANDOM_IDENTITY", "UNKNOWN"]}, "BtPeer": {"description": "Information about the (paired) peer.", "type": "object", "properties": {"address": {"description": "BT address in 00:00:00:00:00:00 format.", "type": "string"}, "addr_type": {"$ref": "#/components/schemas/BtAddressType"}}, "required": ["address", "addr_type"]}, "BtRemoteInfo": {"description": "BT-remote information.\n", "type": "object", "properties": {"profile": {"description": "BT peripheral connection profile", "type": "integer"}, "dev_profile_id": {"description": "Bluetooth device profile identifier.", "type": "string"}, "dev_profile_version": {"description": "Bluetooth device profile version.", "type": "integer", "minimum": 0}, "peer": {"$ref": "#/components/schemas/BtPeer"}, "peripherals": {"$ref": "#/components/schemas/BtDevicePeripherals"}}, "required": ["profile"]}, "BtSecurityType": {"description": "Bonding security type:\n- `JustWorks`: Automatic pairing, peripheral only needs to confirm pairing request from central.\n- `DisplayNumber`: Peripheral must display number for the central to confirm.\n- `NumericComparison`: Peripheral must confirm or declined if the numeric value matches the displayed number on the central.\n- `PasskeyInput`: Peripheral must enter displayed passkey on central.\n", "type": "string", "enum": ["JUST_WORKS", "DISPLAY_NUMBER", "NUMERIC_COMPARISON", "PASSKEY_INPUT"]}, "BtPairingRequest": {"description": "A central requests pairing with the peripheral.\n\u203c\ufe0f Only `kind: PasskeyInput` is currently implemented.\n", "type": "object", "properties": {"id": {"description": "Pairing request identifier", "type": "integer"}, "profile": {"description": "BT peripheral connection profile to associate the pairing request.", "type": "integer"}, "peer": {"$ref": "#/components/schemas/BtPeer"}, "kind": {"$ref": "#/components/schemas/BtSecurityType"}, "passkey": {"description": "Only set for `kind: DisplayNumber | NumericComparison`\n", "type": "integer", "minimum": 0}}, "required": ["profile", "peer", "kind"]}, "BtRemotePairingInfo": {"description": "BT-remote pairing information. The `pairing_request` field is set if a pairing request is active, `peer` is only\nset if the remote has been paired with a central device.\n", "type": "object", "properties": {"pairing_request": {"$ref": "#/components/schemas/BtPairingRequest"}, "paired": {"description": "Indicates if BT-remote entity peripheral is paired with a central device.", "type": "boolean"}, "pairing_enabled": {"description": "Indicates if a central can pair with this BT-remote peripheral.", "type": "boolean"}, "advertisement_name": {"description": "Advertisement name of the peripheral. Usually only set when `pairing_enabled` is true.", "type": "string"}, "peer": {"$ref": "#/components/schemas/BtPeer"}}, "required": ["paired", "pairing_enabled"]}, "BtPairingResponse": {"description": "Response to a BtPairingRequest.\n- `Passkey` request: either provide the passkey entered by the user, decline it with `confirm: false`.\n- `NumericComparison` request: confirm or decline with `confirm: true | false`.\n", "type": "object", "allOf": [{"properties": {"id": {"description": "Pairing request identifier.", "type": "integer"}}, "required": ["id"]}, {"oneOf": [{"type": "object", "properties": {"passkey": {"description": "6-digit passkey displayed on the central, sent as text. Leading zero(s) can be included or omitted.", "type": "string", "minLength": 1, "maxLength": 6}}, "required": ["passkey"]}, {"type": "object", "properties": {"confirm": {"description": "Confirm or decline a pairing request.", "type": "boolean"}}, "required": ["confirm"]}]}]}, "Name": {"type": "string", "minLength": 1, "maxLength": 50}, "Profile": {"type": "object", "properties": {"profile_id": {"$ref": "#/components/schemas/SimpleId"}, "name": {"$ref": "#/components/schemas/Name"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "restricted": {"description": "A restricted profile cannot change settings and switching profiles requires the admin PIN.", "type": "boolean"}, "description": {"$ref": "#/components/schemas/Description"}}, "required": ["profile_id", "name", "restricted"]}, "Profiles": {"type": "array", "items": {"$ref": "#/components/schemas/Profile"}}, "AdminPin": {"type": "string", "maxLength": 20, "description": "Optional administrator pin"}, "ProfileRequest": {"type": "object", "properties": {"profile_id": {"$ref": "#/components/schemas/SimpleId"}, "name": {"$ref": "#/components/schemas/Name"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "restricted": {"description": "Create a restricted profile which cannot change settings. Switching profiles requires the admin pin.", "type": "boolean"}, "description": {"$ref": "#/components/schemas/Description"}}, "required": ["name"]}, "ProfileUpdate": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/Name"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "restricted": {"description": "A restricted profile cannot change settings. Switching profiles requires the admin pin.", "type": "boolean"}, "description": {"$ref": "#/components/schemas/Description"}, "pages": {"description": "Used for update only: modify page order or delete pages in profile.\n- An empty `pages` array will delete all pages and containing groups!\n- If the property is missing, the existing page configuration will not be changed.\n", "type": "array", "items": {"$ref": "#/components/schemas/SimpleId"}}}}, "PageItem": {"type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "group_id": {"$ref": "#/components/schemas/SimpleId"}, "pos": {"type": "integer", "format": "int32", "minimum": 0, "description": "Position of the item within the page. Returned on retrieval, ignored for page updates where the position is taken\nfrom the page array position.\n"}}, "oneOf": [{"required": ["entity_id"]}, {"required": ["group_id"]}]}, "Page": {"type": "object", "properties": {"page_id": {"$ref": "#/components/schemas/SimpleId"}, "profile_id": {"$ref": "#/components/schemas/SimpleId"}, "name": {"$ref": "#/components/schemas/Name"}, "image": {"type": "string", "description": "Optional image identifier"}, "items": {"type": "array", "description": "Page items", "items": {"$ref": "#/components/schemas/PageItem"}}, "pos": {"type": "integer", "format": "int32", "minimum": 0, "description": "Position of the page within the profile"}}, "required": ["page_id", "profile_id", "name", "items", "pos"]}, "ImageIdentifier": {"type": "string", "format": "^[a-z][a-z0-9]+:[a-zA-Z0-9\\-_\\.]+$", "maxLength": 255, "description": "Optional image identifier. The identifier consists of a prefix and a resource identifier, separated by `:`.  \nAvailable prefixes:\n- `custom:` - custom image resource\n\nOther prefixes might be rejected by the service.\n\nAn empty identifier, while updating the object, removes the existing image.\n"}, "PageCreate": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/Name"}, "image": {"$ref": "#/components/schemas/ImageIdentifier"}, "items": {"type": "array", "description": "Optional page items.\n", "items": {"$ref": "#/components/schemas/PageItem"}}, "pos": {"type": "integer", "format": "int32", "minimum": 1, "description": "Optional 1-based position of the page within the profile. Default: last position\n"}}, "required": ["name"]}, "PageUpdate": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/Name"}, "image": {"$ref": "#/components/schemas/ImageIdentifier"}, "items": {"type": "array", "description": "Changed or re-ordered page items.\nAn empty array removes all items.\nIf the property is not specified the defined items will not be changed.\n", "items": {"$ref": "#/components/schemas/PageItem"}}}}, "Group": {"type": "object", "description": "The shown group switch in the UI is automatically determined by the capabilities of the group's entities.\n", "properties": {"group_id": {"$ref": "#/components/schemas/SimpleId"}, "profile_id": {"$ref": "#/components/schemas/SimpleId"}, "name": {"$ref": "#/components/schemas/Name"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "entities": {"type": "array", "description": "Entity identifiers belonging to the group", "items": {"$ref": "#/components/schemas/EntityId"}}, "description": {"$ref": "#/components/schemas/Description"}}, "required": ["group_id", "profile_id", "name", "entities"]}, "Groups": {"type": "array", "items": {"$ref": "#/components/schemas/Group"}}, "GroupUpdate": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/Name"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "entities": {"type": "array", "description": "Changed or re-ordered group entities.\nAn empty array remove all entities.\nIf the property is not specified the defined entities will not be changed.\n", "items": {"$ref": "#/components/schemas/EntityId"}}, "description": {"$ref": "#/components/schemas/Description"}}}, "CfgBt": {"type": "object", "properties": {"peripheral_connections": {"description": "Maximum number of peripheral connections at the same time.", "type": "integer", "minimum": 1}, "advertisement_name": {"description": "Advertisement name of the Remote.", "type": "string"}, "enable_hci_log": {"description": "Enable HCI logging.", "type": "boolean"}, "enable_debug_port": {"description": "Enable BT subsystem debug TCP-port for remote control.", "type": "boolean"}, "version": {"description": "BT subsystem version.", "type": "string"}}, "required": ["peripheral_connections", "advertisement_name", "enable_hci_log", "enable_debug_port"]}, "StaticButtonColor": {"description": "Static color settings for given zones, if supported by the device.", "type": "object", "properties": {"rgb": {"description": "The overall rgb color value for the specified zones [int, int, int].", "type": "array", "items": {"type": "integer", "minimum": 0, "maximum": 255}, "minItems": 3, "maxItems": 3}, "zones": {"description": "The enabled backlight zones. All zones are enabled if no zones are set.", "type": "array", "items": {"type": "string", "minimum": 1, "maximum": 50}, "maxItems": 32}}, "required": ["rgb"]}, "CfgButtons": {"type": "object", "properties": {"brightness": {"description": "Button backlight brightness. 0 = off, 100 = max.", "type": "integer", "minimum": 0, "maximum": 100}, "static_color": {"$ref": "#/components/schemas/StaticButtonColor"}, "auto_brightness": {"description": "When enabled, button backlight will automatically turn on in a dark room.", "type": "boolean"}, "features": {"description": "Supported features by the device.", "type": "array", "items": {"type": "string"}}}, "required": ["brightness", "auto_brightness"]}, "CfgRemoteDevice": {"type": "object", "properties": {"name": {"description": "Custom name of the remote", "type": "string", "minimum": 1, "maximum": 50}}, "required": ["name"]}, "CfgDisplay": {"type": "object", "properties": {"brightness": {"description": "Display brightness.", "type": "integer", "minimum": 0, "maximum": 100}, "auto_brightness": {"description": "Automatically adjust the display brightness based on ambient lighting conditions.", "type": "boolean"}}, "required": ["brightness", "auto_brightness"]}, "CfgFeature": {"type": "object", "properties": {"id": {"type": "string"}, "enabled": {"type": "boolean"}, "title": {"$ref": "#/components/schemas/LanguageText"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "help_url": {"type": "string", "format": "url"}}, "required": ["id", "enabled", "title", "description"]}, "CfgFeatures": {"type": "array", "items": {"$ref": "#/components/schemas/CfgFeature"}}, "CfgHaptic": {"type": "object", "properties": {"enabled": {"description": "Haptic feedback enabled.", "type": "boolean"}}, "required": ["enabled"]}, "LanguageCode": {"description": "Language culture code: starting with the two-letter [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)\ncode, followed by an optional [ISO-3166 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes),\nseparated by an underscore.\nExamples: `en`, `en_UK`, `en_US`, `de`, `de_DE`, `de_CH` etc.\n", "type": "string", "pattern": "^[a-z]{2}(_\\w+)?$"}, "CountryCode": {"description": "Two letter country code according to [ISO-3166-1-alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).", "type": "string", "format": "iso-3166"}, "MeasurementUnit": {"type": "string", "enum": ["METRIC", "US", "UK"]}, "CfgLocalization": {"type": "object", "properties": {"language_code": {"$ref": "#/components/schemas/LanguageCode"}, "country_code": {"$ref": "#/components/schemas/CountryCode"}, "time_zone": {"description": "Time zone name according to IANA <https://www.iana.org/time-zones>, e.g. `Europe/Copenhagen`.", "type": "string"}, "time_format_24h": {"type": "boolean"}, "measurement_unit": {"$ref": "#/components/schemas/MeasurementUnit"}}, "required": ["language_code", "country_code", "time_zone", "time_format_24h", "measurement_unit"]}, "CfgNetworkWoWlan": {"description": "Wake on WLAN settings", "type": "object", "properties": {"enabled": {"description": "Enable Wake on WLAN.", "type": "boolean"}}, "required": ["enabled"]}, "WifiBand": {"description": "WiFi band:\n- `auto`: auto-configuration\n- `a`: 5 GHz\n- `b`: 2.4 GHz\n", "type": "string", "enum": ["auto", "a", "b"]}, "WifiScanInterval": {"description": "Active WiFi scan interval in seconds. A value of 0 disables active scanning. Minimal interval is 10 seconds.\n", "minimum": 0, "type": "integer"}, "CfgIpv4Type": {"type": "string", "enum": ["DHCP"]}, "CfgIpv4": {"type": "object"}, "CfgNetworkWifi": {"type": "object", "properties": {"wake_on_wlan": {"$ref": "#/components/schemas/CfgNetworkWoWlan"}, "bands": {"description": "Available WiFi bands", "type": "array", "items": {"$ref": "#/components/schemas/WifiBand"}}, "band": {"$ref": "#/components/schemas/WifiBand"}, "scan_interval_sec": {"$ref": "#/components/schemas/WifiScanInterval"}, "ipv4_type": {"$ref": "#/components/schemas/CfgIpv4Type"}, "ipv4": {"$ref": "#/components/schemas/CfgIpv4"}}, "required": ["bands", "band"]}, "CfgNetworkWs": {"description": "Optional expert settings for WebSocket (re-)connection handling.  \nThese settings are only intended for support issues and might change any time. Changed values are not supported\nand might make the system unstable!\n", "type": "object", "properties": {"dock": {"type": "object"}, "integration": {"type": "object"}}}, "CfgNetwork": {"description": "`wake_on_wlan` is deprecated, please use `wifi.wake_on_wlan`\n", "type": "object", "properties": {"bt_enabled": {"description": "Enable Bluetooth.", "type": "boolean"}, "wifi_enabled": {"description": "Enable WiFi.", "type": "boolean"}, "wake_on_wlan": {"$ref": "#/components/schemas/CfgNetworkWoWlan"}, "wifi": {"$ref": "#/components/schemas/CfgNetworkWifi"}, "bt": {"description": "Temporary read-only Bluetooth information until dedicated BT management endpoint is provided.", "type": "object", "properties": {"address": {"description": "Bluetooth MAC address", "type": "string"}}}, "ws": {"$ref": "#/components/schemas/CfgNetworkWs"}}, "required": ["bt_enabled", "wifi_enabled"]}, "CfgPowerSaving": {"type": "object", "properties": {"wakeup_sensitivity": {"description": "Amount of movement needed to wake up the remote. 0 = disabled, 1 = min, 2 = medium, 3 = max.", "type": "integer", "minimum": 0, "maximum": 3}, "display_off_sec": {"type": "integer", "minimum": 0, "maximum": 60, "description": "Turn off display after given seconds."}, "standby_sec": {"type": "integer", "minimum": 0, "maximum": 10800, "description": "Activate standby after given seconds. 0 disables standby mode."}}, "required": ["wakeup_sensitivity", "display_off_sec", "standby_sec"]}, "CfgProfile": {"type": "object", "properties": {"has_admin_pin": {"description": "An administrator pin has been set to use restricted profiles.", "type": "boolean"}}, "required": ["has_admin_pin"]}, "CfgSoftwareUpdate": {"type": "object", "properties": {"check_for_updates": {"description": "Automatically check for updates. If `auto_update` is enabled, the updates are automatically installed,\notherwise the user is only notified about the updates.\n\nThe time window when to check for new updates can be specified in `ota_window_start` and `ota_window_end`.\nUpdate checks are performed daily.\n", "type": "boolean"}, "auto_update": {"description": "Automatically update the remote when new software is available. Requires `check_for_updates` to be enabled.\n\nAuto-installation of new firmwares will usually happen over 2 update checks: the first check finds a new\nupdate, downloads the metadata and schedules the firmware file to be downloaded. The next check will find the\ndownloaded firmware file and installs it.\n", "type": "boolean"}, "ota_window_start": {"description": "OTA update window start time: automatic update checks will only be performed during this time window.  \nFurthermore, the remote needs to be in the docking station and have enough battery charge.\n\nFormat: time of day - as defined by `partial-time` in RFC3339\n", "type": "string", "pattern": "^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$"}, "ota_window_end": {"description": "OTA update window end time.\n\n- If the end time is before the start time, the window will spawn over midnight, e.g. `23:00:00` - `01:00:00`.\n- Both start and end times are required, otherwise a default will be used.\n", "type": "string", "pattern": "^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$"}, "channel": {"description": "Software update channels:\n- `DEFAULT`: release channel\n- `TESTING`: new test and beta versions which might become the next release if successfully tested.\n- `DEVELOPMENT`: untested alpha versions from the developers.  \n   \u26a0\ufe0f High chance of breaking changes, bugs and loosing data!\n\nOther channels than `DEFAULT` might require an access token in `channel_token`, since they are intended for\na closed user group.\n", "type": "string", "anyOf": [{"enum": ["DEFAULT", "TESTING", "DEVELOPMENT"]}, {}]}, "channel_token": {"description": "Optional access token which might be required for non-default software update channels.\n- This token is write only and cannot be retrieved anymore.\n- If omitted when updating settings: the stored token will be used.\n- If the `default` channel is selected when updating settings: the token will be ignored.\n", "type": "string", "pattern": "^[-a-zA-Z0-9._~+/]{1,256}=?$"}, "restart_required": {"description": "Optional response field only: a configuration change requires a restart.", "type": "boolean"}}, "required": ["check_for_updates", "auto_update"]}, "CfgSound": {"type": "object", "properties": {"enabled": {"description": "Sound effects enabled.", "type": "boolean"}, "volume": {"description": "Sound effects volume.", "type": "integer", "minimum": 0, "maximum": 100}}, "required": ["enabled", "volume"]}, "VoiceAssistantFeature": {"description": "Supported voice assistant or profile features.\n- transcription: Supports voice command transcription.\n- response_text: Supports textual response about the performed action.\n- response_speech: Supports speech response about the performed action.\n", "type": "string", "enum": ["transcription", "response_text", "response_speech"]}, "VoiceAssistantFeatures": {"type": "array", "items": {"$ref": "#/components/schemas/VoiceAssistantFeature"}}, "VoiceAssistantProfile": {"description": "Profiles are optional and allow parameterizing voice input. A regular voice-capable device usually just accepts voice\ninput without additional parameters. Home automation systems can offer multi-language support or an option to use\nlocal or cloud processing.\n\nFor example, Home Assistant allows configuring multiple Assist pipelines for voice commands.\nThese pipelines can offer different languages or speech recognition engines.\n\n- `language` is an optional language code if the profile represents a specific language for speech recognition.\n- `features` is optional and overwrites the voice assistant features, for example, if a profile has less or more features.\n- An empty `features` array means \"no features\".\n", "type": "object", "properties": {"id": {"$ref": "#/components/schemas/SimpleId"}, "name": {"description": "Friendly name to show in UI.", "type": "string", "minLength": 1, "maxLength": 50}, "language": {"$ref": "#/components/schemas/LanguageCode"}, "features": {"$ref": "#/components/schemas/VoiceAssistantFeatures"}}, "required": ["id", "name"]}, "VoiceAssistantProfiles": {"type": "array", "items": {"$ref": "#/components/schemas/VoiceAssistantProfile"}}, "VoiceAssistant": {"description": "Voice assistant definition.\n\nThis is a tailored representation of the voice_assistant entity, which can be used to display voice assistant\ninformation to users.\n\n- `profiles` specify optional parameters that can be used by starting a voice command.\n- `features` are the default features supported by the voice assistant.  \n   If multiple profiles are supported, this should be the feature list of the preferred profile.\n- `preferred_profile` is the preferred profile specified by the integration.  \n   The user can select another default profile in the voice assistant settings.\n", "type": "object", "properties": {"entity_id": {"$ref": "#/components/schemas/EntityId"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "state": {"type": "string"}, "features": {"$ref": "#/components/schemas/VoiceAssistantFeatures"}, "profiles": {"$ref": "#/components/schemas/VoiceAssistantProfiles"}, "preferred_profile": {"$ref": "#/components/schemas/SimpleId"}}, "required": ["entity_id", "name"]}, "CfgVoiceAssistant": {"description": "The main voice assistant to use for voice control, if no other voice assistant is configured for a specific\nscreen, for example, in an activity.\n", "type": "object", "properties": {"active": {"$ref": "#/components/schemas/VoiceAssistant"}, "profile_id": {"$ref": "#/components/schemas/SimpleId"}, "speech_response": {"description": "Enable speech response if supported by the voice assistant. Disabled by default.", "type": "boolean", "default": false}}}, "CfgVoiceControl": {"description": "Voice control settings with enriched voice assistant configuration.\nNo voice assistant is enabled if the `voice_assistant.active` object is missing.\n", "type": "object", "properties": {"microphone": {"description": "Enable microphone. Disabling the microphone will completely turn it off. Voice control and dictation won't work\nwith the remote or integrations.\n", "type": "boolean"}, "voice_assistant": {"$ref": "#/components/schemas/CfgVoiceAssistant"}}, "required": ["microphone", "voice_assistant"]}, "CfgAll": {"type": "object", "properties": {"bt": {"$ref": "#/components/schemas/CfgBt"}, "button": {"$ref": "#/components/schemas/CfgButtons"}, "device": {"$ref": "#/components/schemas/CfgRemoteDevice"}, "display": {"$ref": "#/components/schemas/CfgDisplay"}, "features": {"$ref": "#/components/schemas/CfgFeatures"}, "haptic": {"$ref": "#/components/schemas/CfgHaptic"}, "localization": {"$ref": "#/components/schemas/CfgLocalization"}, "network": {"$ref": "#/components/schemas/CfgNetwork"}, "power_saving": {"$ref": "#/components/schemas/CfgPowerSaving"}, "profile": {"$ref": "#/components/schemas/CfgProfile"}, "software_update": {"$ref": "#/components/schemas/CfgSoftwareUpdate"}, "sound": {"$ref": "#/components/schemas/CfgSound"}, "voice": {"$ref": "#/components/schemas/CfgVoiceControl"}, "restart_required": {"description": "A configuration change requires a restart.", "type": "boolean"}}}, "CfgBtUpdate": {"type": "object", "properties": {"peripheral_connections": {"description": "Maximum number of peripheral connections at the same time.", "type": "integer", "minimum": 1}, "enable_hci_log": {"description": "Enable HCI logging.", "type": "boolean"}, "enable_debug_port": {"description": "Enable BT subsystem debug TCP-port for remote control.", "type": "boolean"}}}, "BtDeviceProfileInfo": {"description": "BT device profile overview information. Contains all required device information to make a device selection.\n", "type": "object", "properties": {"id": {"description": "Device profile identifier", "type": "string"}, "user_profile": {"description": "System or user provided device profile.", "type": "boolean"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "version": {"type": "integer"}, "peripherals": {"$ref": "#/components/schemas/BtDevicePeripherals"}}, "required": ["id", "name", "version", "peripherals"]}, "BtDeviceProfileInfos": {"type": "array", "items": {"$ref": "#/components/schemas/BtDeviceProfileInfo"}}, "BtDeviceProfile": {"description": "BT device profile to define available key commands and pre-defined button mappings and UI screens.\n", "type": "object", "properties": {"id": {"description": "Device profile identifier", "type": "string"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "version": {"type": "integer"}, "peripherals": {"$ref": "#/components/schemas/BtDevicePeripherals"}, "commands": {"type": "object", "properties": {"keyboard": {"type": "array", "items": {"type": "string"}}, "consumer": {"type": "array", "items": {"type": "string"}}, "system": {"type": "array", "items": {"type": "string"}}}, "required": ["keyboard", "consumer", "system"]}, "command_mapping": {"type": "object", "additionalProperties": {"type": "string"}}, "button_mapping": {"$ref": "#/components/schemas/DeviceButtonMappings"}, "user_interface": {"$ref": "#/components/schemas/ActivityUserInterface"}}, "required": ["id", "name", "version", "peripherals", "commands", "command_mapping"]}, "CfgButtonsUpdate": {"description": "Button configuration model to update settings. Missing properties are not changed.", "type": "object", "properties": {"brightness": {"description": "Overall button backlight brightness. 0 = off, 100 = max.", "type": "integer", "minimum": 0, "maximum": 100}, "static_color": {"$ref": "#/components/schemas/StaticButtonColor"}, "auto_brightness": {"description": "When enabled, button backlight will automatically turn on in a dark room.", "type": "boolean"}}}, "DeviceButtonGroup": {"description": "Button group type, either physical buttons or button backlight zones:\n- `keypad`: physical keypad buttons.\n- `keypad_backlight`: button backlight zones.\n", "type": "string", "enum": ["keypad", "keypad_backlight"]}, "DeviceButtonLayout": {"description": "Button group definitions with layout placement, size, icon and language specific names.\n\nThe grid width & height definitions do not need to be proportional! To get the correct size, the grid has to be\nplaced over the physical dimensions of the button group. For example if buttons in a row can be placed in the middle\nof another button row, the width value can be doubled, with the button width set to 2.\n", "type": "object", "properties": {"type": {"$ref": "#/components/schemas/DeviceButtonGroup"}, "grid": {"$ref": "#/components/schemas/GridSize"}, "buttons": {"type": "array", "items": {"type": "object", "properties": {"button": {"description": "Unique button identifier over all button groups.", "type": "string"}, "icon": {"$ref": "#/components/schemas/IconIdentifier"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "location": {"$ref": "#/components/schemas/GridLocation"}, "size": {"$ref": "#/components/schemas/GridItemSize"}}, "required": ["button", "icon", "name", "location"]}}}, "required": ["type", "grid", "buttons"]}, "DeviceScreenLayout": {"description": "Screen layout definitions with usable grid sizes for custom UI pages.", "type": "object", "properties": {"grid": {"type": "object", "properties": {"default": {"$ref": "#/components/schemas/GridSize"}, "min": {"$ref": "#/components/schemas/GridSize"}, "max": {"$ref": "#/components/schemas/GridSize"}}, "required": ["default", "min", "max"]}}, "required": ["grid"]}, "EntityCmdParamNumber": {"type": "object", "description": "Number value parameter with optional limits.   \n", "allOf": [{"$ref": "#/components/schemas/EntityCmdParamCommon"}, {"properties": {"default": {"description": "Default value to use, e.g. in a UI editor.", "type": "number"}, "min": {"description": "Minimal allowed value (inclusive).", "type": "number", "default": 0}, "max": {"description": "Maximal allowed value (inclusive).", "type": "number"}, "step": {"description": "Step size between values.", "type": "number", "default": 1}, "unit": {"description": "Optional unit label of the value.", "type": "string"}}}], "examples": [{"name": {"en": "Brightness"}, "param": "brightness", "type": "number", "default": 22, "min": 0, "max": 100, "step": 1, "unit": "%"}]}, "EntityCmdParamBool": {"type": "object", "description": "Boolean value parameter.", "allOf": [{"$ref": "#/components/schemas/EntityCmdParamCommon"}]}, "EntityCmdParamRegex": {"type": "object", "description": "Text value parameter with optional regex validation.", "allOf": [{"$ref": "#/components/schemas/EntityCmdParamCommon"}, {"properties": {"regex": {"description": "Validation regex.", "type": "string"}, "default": {"description": "Default value to use, e.g. in a UI editor.", "type": "string"}}}], "examples": [{"name": {"en": "Text"}, "param": "text", "type": "regex", "regex": "^.{0,255}$", "default": "foobar"}]}, "EntityCmdParamEnum": {"type": "object", "description": "Enumeration parameter. Only the defined values are allowed as parameter value.", "allOf": [{"$ref": "#/components/schemas/EntityCmdParamCommon"}, {"properties": {"values": {"type": "array", "items": {"type": "string"}}, "default": {"description": "Default value for a new command. Must be a value defined in `values`", "type": "string"}}, "required": ["values"]}], "examples": [{"name": {"en": "Mode"}, "param": "mode", "type": "enum", "values": ["Option 1", "Option 2", "Option 3"], "default": "Option 1"}]}, "EntityCmdParamSelection": {"type": "object", "description": "Text value parameter with a selection list from another entity field.", "allOf": [{"$ref": "#/components/schemas/EntityCmdParamCommon"}, {"properties": {"items": {"description": "Validation regex.", "type": "object", "properties": {"source": {"description": "Where to load the selection list from.", "type": "string", "enum": ["attributes", "options"]}, "field": {"description": "Field name in the source object containing an array of strings for the parameter selection\n", "type": "string"}}, "required": ["source", "field"]}}, "required": ["items"]}], "examples": [{"name": {"en": "Input"}, "param": "input", "type": "selection", "items": {"source": "attributes", "field": "source_list"}}]}, "EntityCmdParamCommon": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "param": {"description": "Parameter name.", "type": "string"}, "type": {"description": "Parameter type.", "type": "string", "enum": ["number", "bool", "regex", "enum", "selection"]}, "optional": {"description": "Parameter is optional.", "type": "boolean", "default": false}}, "required": ["name", "param", "type"]}, "EntityCommandMetadata": {"type": "object", "properties": {"id": {"description": "Entity command identifier to be used in activity and macro commands (button mappings, UI elements and sequences).\n\nThis identifier may change at any time and may not be used for logic decisions in a client!\nIf entity specific information is required, the entity object must be used.\n", "type": "string"}, "cmd_id": {"description": "Entity command as specified in the [entity documentation](https://github.com/unfoldedcircle/core-api/tree/main/doc/entities).\nThis is the command identifier being sent to integration drivers.\n", "type": "string"}, "name": {"$ref": "#/components/schemas/LanguageText"}, "params": {"description": "Metadata describing the optional parameters of the command. Simple \"button like\" commands\ndon't have any parameters, whereas e.g. a light entity can also dim the light, change color or color\ntemperature.\n", "type": "array", "items": {"oneOf": [{"$ref": "#/components/schemas/EntityCmdParamNumber"}, {"$ref": "#/components/schemas/EntityCmdParamBool"}, {"$ref": "#/components/schemas/EntityCmdParamRegex"}, {"$ref": "#/components/schemas/EntityCmdParamEnum"}, {"$ref": "#/components/schemas/EntityCmdParamSelection"}], "discriminator": {"propertyName": "type", "mapping": {"number": "#/components/schemas/EntityCmdParamNumber", "bool": "#/components/schemas/EntityCmdParamBool", "regex": "#/components/schemas/EntityCmdParamRegex", "enum": "#/components/schemas/EntityCmdParamEnum", "selection": "#/components/schemas/EntityCmdParamSelection"}}}}}, "required": ["id", "cmd_id", "name"]}, "CfgFeatureUpdate": {"type": "object", "properties": {"id": {"type": "string"}, "enabled": {"type": "boolean"}}, "required": ["id", "enabled"]}, "CfgNetworkWifiUpdate": {"type": "object", "properties": {"wake_on_wlan": {"$ref": "#/components/schemas/CfgNetworkWoWlan"}, "band": {"$ref": "#/components/schemas/WifiBand"}, "scan_interval_sec": {"$ref": "#/components/schemas/WifiScanInterval"}}}, "CfgNetworkUpdate": {"description": "`wake_on_wlan` is deprecated, please use `wifi.wake_on_wlan`\n", "type": "object", "properties": {"bt_enabled": {"description": "Enable Bluetooth.", "type": "boolean"}, "wifi_enabled": {"description": "Enable WiFi.", "type": "boolean"}, "wake_on_wlan": {"$ref": "#/components/schemas/CfgNetworkWoWlan"}, "wifi": {"$ref": "#/components/schemas/CfgNetworkWifiUpdate"}, "ws": {"$ref": "#/components/schemas/CfgNetworkWs"}}}, "CfgProfileUpdate": {"type": "object", "properties": {"admin_pin": {"$ref": "#/components/schemas/AdminPin"}}}, "CfgVoiceAssistantUpdate": {"description": "The main voice assistant to use for voice control, if no other voice assistant is configured for a specific\nscreen, for example, in an activity.\n", "type": "object", "properties": {"entity_id": {"description": "Voice assistant entity id to use, empty for removing a configured voice assistant.", "type": "string"}, "profile_id": {"$ref": "#/components/schemas/SimpleId"}, "speech_response": {"description": "Enable speech response if supported by the voice assistant. Disabled by default.", "type": "boolean"}}, "required": ["entity_id"]}, "CfgVoiceControlUpdate": {"description": "Update object for voice control settings. A missing field will keep the old value.\n", "type": "object", "properties": {"microphone": {"description": "Enable microphone. Disabling the microphone will completely turn it off. Voice control and dictation won't work\nwith the remote or integrations.\n", "type": "boolean"}, "voice_assistant": {"$ref": "#/components/schemas/CfgVoiceAssistantUpdate"}}}, "VoiceAssistants": {"type": "array", "items": {"$ref": "#/components/schemas/VoiceAssistant"}}, "DockId": {"type": "string", "format": "^[a-zA-Z0-9\\-\\.]+$", "minLength": 1, "maxLength": 64, "description": "Dock identifier"}, "DockName": {"type": "string", "minLength": 1, "maxLength": 40, "description": "User assignable friendly name to use instead of dock_id (service name)."}, "DockUrl": {"type": "string", "maxLength": 64, "description": "Dock WebSocket URL to override auto-discovery from the service name in `dock_id`."}, "DockState": {"type": "string", "description": "Dock connection state", "enum": ["IDLE", "CONNECTING", "ACTIVE", "RECONNECTING", "ERROR"]}, "ExternalPortNumber": {"description": "1-based port index number.", "type": "integer", "minimum": 1}, "ExternalPortMode": {"type": "string", "enum": ["AUTO", "NONE", "INFRARED", "IR_BLASTER", "IR_EMITTER_MONO_PLUG", "IR_EMITTER_STEREO_PLUG", "TRIGGER_5V", "RS232"]}, "ExternalPortActiveMode": {"type": "string", "enum": ["UNKNOWN", "NONE", "ERROR", "INFRARED", "IR_BLASTER", "IR_EMITTER_MONO_PLUG", "IR_EMITTER_STEREO_PLUG", "TRIGGER_5V", "RS232"]}, "UartBaudRate": {"description": "Common baud rate values: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200\n", "type": "integer", "minimum": 300, "maximum": 115200, "default": 9600}, "UartDataBits": {"type": "integer", "minimum": 5, "maximum": 8, "default": 8}, "UartStopBits": {"description": "Stop bits must be set as string, number format is not supported!", "type": "string", "enum": ["1", "1.5", "2"], "default": "1"}, "UartParity": {"type": "string", "enum": ["none", "even", "odd"], "default": "none"}, "UartConfiguration": {"type": "object", "properties": {"baud_rate": {"$ref": "#/components/schemas/UartBaudRate"}, "data_bits": {"$ref": "#/components/schemas/UartDataBits"}, "stop_bits": {"$ref": "#/components/schemas/UartStopBits"}, "parity": {"$ref": "#/components/schemas/UartParity"}}, "required": ["baud_rate", "data_bits", "stop_bits", "parity"]}, "ExternalPortConfiguration": {"description": "External port configuration.\n- `mode`: configured operation mode.\n- `active_mode`: active operation mode, usually only set with the detected peripheral for `mode: AUTO`.\n", "type": "object", "properties": {"port": {"$ref": "#/components/schemas/ExternalPortNumber", "readOnly": true}, "mode": {"$ref": "#/components/schemas/ExternalPortMode"}, "active_mode": {"$ref": "#/components/schemas/ExternalPortActiveMode", "readOnly": true}, "supported_modes": {"description": "Supported modes of the port.", "type": "array", "items": {"$ref": "#/components/schemas/ExternalPortMode"}, "readOnly": true}, "uart": {"$ref": "#/components/schemas/UartConfiguration"}}, "required": ["port", "mode"]}, "DockConfiguration": {"type": "object", "properties": {"dock_id": {"$ref": "#/components/schemas/DockId"}, "name": {"$ref": "#/components/schemas/DockName"}, "custom_ws_url": {"$ref": "#/components/schemas/DockUrl"}, "resolved_ws_url": {"type": "string", "maxLength": 64, "description": "Resolved WebSocket URL from the service name in `dock_id` if no `custom_ws_url` is used."}, "active": {"type": "boolean", "description": "Enable flag: active docks are automatically connected when network is available.\n"}, "model": {"type": "string", "description": "Dock model number."}, "revision": {"type": "string", "description": "Dock revision."}, "serial": {"type": "string", "description": "Dock serial number."}, "led_brightness": {"type": "integer", "minimum": 0, "maximum": 100}, "eth_led_brightness": {"type": "integer", "minimum": 0, "maximum": 100}, "connection_type": {"type": "string", "description": "Network connection of the dock: `Ethernet` or `WiFi`.\n"}, "version": {"type": "string", "description": "Firmware version"}, "state": {"$ref": "#/components/schemas/DockState"}, "learning_active": {"type": "boolean", "description": "Dock is in IR learning mode."}, "port_count": {"type": "integer", "minimum": 0}, "ports": {"description": "3\ufe0f\u20e3 External port mode configuration.", "type": "array", "items": {"$ref": "#/components/schemas/ExternalPortConfiguration"}}, "volume": {"description": "3\ufe0f\u20e3 Speaker volume.", "type": "integer", "minimum": 0, "maximum": 100}, "description": {"$ref": "#/components/schemas/Description"}}, "required": ["dock_id", "active"]}, "DockConfigurations": {"type": "array", "items": {"$ref": "#/components/schemas/DockConfiguration"}}, "DockToken": {"type": "string", "format": "password", "minLength": 1, "maxLength": 40, "description": "Access token"}, "DockConfigurationRequest": {"type": "object", "properties": {"dock_id": {"$ref": "#/components/schemas/DockId"}, "name": {"$ref": "#/components/schemas/DockName"}, "custom_ws_url": {"$ref": "#/components/schemas/DockUrl"}, "token": {"$ref": "#/components/schemas/DockToken"}, "active": {"type": "boolean", "description": "Enable flag: active docks are automatically connected when network is available.\n"}, "model": {"type": "string", "description": "Dock model number."}, "description": {"$ref": "#/components/schemas/Description"}}, "required": ["dock_id", "active"]}, "DiscoveryType": {"type": "string", "description": "Device discovery type:\n- `BT`: Bluetooth\n- `NET`: LAN or WAN network\n", "enum": ["BT", "NET"]}, "DockDiscovery": {"type": "object", "properties": {"id": {"$ref": "#/components/schemas/DockId"}, "configured": {"description": "Dock configuration flag for this remote:\n- true: device has already been configured\n- false: device has not yet been configured\n", "type": "boolean"}, "friendly_name": {"$ref": "#/components/schemas/DockName"}, "address": {"description": "Resolved device network address.", "type": "string"}, "model": {"description": "Detected dock model.", "type": "string"}, "version": {"description": "Detected firmware version.", "type": "string"}, "discovery_type": {"$ref": "#/components/schemas/DiscoveryType"}, "timestamp": {"description": "Timestamp of dock discovery.", "type": "string", "format": "date-time"}, "bt": {"type": "object", "description": "Optional Bluetooth discovery information. Not present for network device.", "properties": {"signal": {"description": "Bluetooth signal strength. 0 = min, 5 = max.", "type": "integer", "minimum": 0, "maximum": 5}, "last_seen_sec": {"description": "Last time the device was seen on a Bluetooth scan. Values over 15 sec indicate that the device is no longer\nreachable.\n", "type": "integer", "format": "int32"}}}}, "required": ["id", "configured", "discovery_type"]}, "DockDiscoveryStatus": {"type": "object", "properties": {"active": {"description": "Dock discovery still active or not.\n", "type": "boolean"}, "docks": {"type": "array", "items": {"$ref": "#/components/schemas/DockDiscovery"}}}, "required": ["active", "docks"]}, "DockSystemInfo": {"type": "object", "properties": {"name": {"type": "string"}, "hostname": {"type": "string"}, "model": {"type": "string"}, "revision": {"type": "string"}, "version": {"type": "string"}, "serial": {"type": "string"}, "ir_learning": {"type": "boolean"}, "ethernet": {"type": "boolean"}, "wifi": {"type": "boolean"}, "ssid": {"description": "Network name (Service Set IDentifier)", "type": "string"}}}, "DockSetupFromDiscovery": {"type": "object", "properties": {"id": {"$ref": "#/components/schemas/DockId"}, "friendly_name": {"$ref": "#/components/schemas/DockName"}, "address": {"description": "Resolved device network address.", "type": "string"}, "model": {"description": "Detected dock model.", "type": "string"}, "version": {"description": "Detected firmware version.", "type": "string"}, "discovery_type": {"$ref": "#/components/schemas/DiscoveryType"}}, "required": ["id", "discovery_type"]}, "DockSetup": {"type": "object", "description": "Dock setup data", "properties": {"name": {"$ref": "#/components/schemas/DockName"}, "token": {"$ref": "#/components/schemas/DockToken"}, "custom_ws_url": {"$ref": "#/components/schemas/DockUrl"}, "description": {"$ref": "#/components/schemas/Description"}, "wifi": {"description": "Optional WiFi information if the dock should connect to (or be prepared for) WiFi instead of Ethernet.\n", "type": "object", "properties": {"ssid": {"description": "Network name (Service Set IDentifier)", "type": "string"}, "password": {"type": "string", "format": "password"}}, "required": ["ssid", "password"]}}, "required": ["name"]}, "CreateDockSetup": {"type": "object", "oneOf": [{"type": "object", "properties": {"discovery": {"$ref": "#/components/schemas/DockSetupFromDiscovery"}}, "required": ["discovery"]}, {"type": "object", "properties": {"manually": {"$ref": "#/components/schemas/DockSetup"}}, "required": ["manually"]}]}, "DockSetupState": {"type": "string", "enum": ["NEW", "CONFIGURING", "UPLOADING", "RESTARTING", "OK", "ERROR"]}, "DockSetupError": {"type": "string", "enum": ["NONE", "NOT_FOUND", "CONNECTION_ERROR", "CONNECTION_REFUSED", "AUTHORIZATION_ERROR", "TIMEOUT", "ABORT", "PERSISTENCE_ERROR", "OTHER"]}, "DockSetupInfo": {"type": "object", "description": "Dock setup state", "properties": {"id": {"type": "string"}, "name": {"$ref": "#/components/schemas/DockName"}, "model": {"type": "string", "description": "Dock model number."}, "discovery_type": {"$ref": "#/components/schemas/DiscoveryType"}, "state": {"$ref": "#/components/schemas/DockSetupState"}, "error": {"$ref": "#/components/schemas/DockSetupError"}}, "required": ["id", "state"]}, "DockUpdateRequest": {"type": "object", "properties": {"name": {"type": "string", "maxLength": 40, "description": "User assignable friendly name to use instead of dock_id (service name)."}, "custom_ws_url": {"$ref": "#/components/schemas/DockUrl"}, "token": {"type": "string", "maxLength": 40, "description": "Access token to connect to the dock."}, "active": {"type": "boolean", "description": "Auto connect to dock when network is available."}, "description": {"type": "string", "description": "Optional description."}, "wifi": {"type": "object", "properties": {"ssid": {"description": "Network name (Service Set IDentifier)", "type": "string", "maxLength": 32}, "password": {"type": "string", "maxLength": 63}}}}}, "UpdateChannel": {"type": "string", "enum": ["STABLE", "TESTING", "DEVELOPMENT"]}, "UpdateDownloadState": {"description": "Download status:\n- `PENDING`: update is scheduled to download\n- `DOWNLOADING`: update is currently downloading\n- `DOWNLOADED`: update has been downloaded and is ready to be installed\n- `ERROR`: download failed\n", "type": "string", "enum": ["PENDING", "DOWNLOADING", "DOWNLOADED", "ERROR"]}, "DockFirmwareUpdate": {"type": "object", "description": "Dock firmware information", "properties": {"model": {"description": "Dock model", "type": "string"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "version": {"type": "string"}, "channel": {"$ref": "#/components/schemas/UpdateChannel"}, "release_date": {"type": "string", "format": "date"}, "size": {"type": "integer", "format": "int64"}, "release_notes_url": {"type": "string", "format": "uri"}, "download": {"$ref": "#/components/schemas/UpdateDownloadState"}}, "required": ["model", "description", "version"]}, "DockUpdateCheck": {"type": "object", "description": "Dock firmware update check information.", "properties": {"dock_id": {"type": "string"}, "version": {"description": "Installed firmware version.", "type": "string"}, "update_available": {"description": "Whether or not an update is available. An available update is set in the `firmware_update` object.", "type": "boolean"}, "update_check_enabled": {"description": "Whether or not the online update check is enabled or not. If disabled, `update_available` will always be false.\n", "type": "boolean"}, "firmware_update": {"$ref": "#/components/schemas/DockFirmwareUpdate"}, "update_id": {"description": "Update identifier if an update is currently in progress.", "type": "string"}}, "required": ["dock_id", "version", "update_available", "update_check_enabled"]}, "DockUpdateProgress": {"type": "object", "description": "Dock firmware update progress", "properties": {"dock_id": {"type": "string"}, "update_id": {"description": "Update identifier", "type": "string"}, "version": {"description": "Firmware version being installed", "type": "string"}, "progress": {"description": "Update progress in percent", "type": "integer", "format": "int32", "minimum": 0, "maximum": 100}, "state": {"$ref": "#/components/schemas/DockSetupState"}, "error": {"$ref": "#/components/schemas/DockSetupError"}}, "required": ["dock_id", "update_id", "version", "state"]}, "ExternalPortConfigurations": {"type": "array", "items": {"$ref": "#/components/schemas/ExternalPortConfiguration"}}, "ExternalPortConfigurationRequest": {"type": "object", "properties": {"mode": {"$ref": "#/components/schemas/ExternalPortMode"}, "uart": {"$ref": "#/components/schemas/UartConfiguration"}}, "required": ["mode"]}, "SystemInfo": {"type": "object", "properties": {"model_name": {"description": "Friendly name of the device model.", "type": "string"}, "model_number": {"description": "Full model number of the remote:\n- `ucr2` for Remote Two\n- `ucr3-##` for Remote 3, ## suffix indicates color variant\n", "type": "string"}, "serial_number": {"type": "string"}, "hw_revision": {"type": "string"}}}, "BackupReportItem": {"type": "string", "enum": ["db", "integration_driver", "integration", "activity", "macro", "remote", "profile", "dock", "resource"]}, "BackupReport": {"type": "object", "properties": {"item": {"$ref": "#/components/schemas/BackupReportItem"}, "available": {"type": "integer", "format": "int32"}, "ok": {"type": "integer", "format": "int32"}}, "required": ["item", "available", "ok"]}, "BackupReports": {"type": "array", "items": {"$ref": "#/components/schemas/BackupReport"}}, "BackupSnapshot": {"type": "object", "properties": {"id": {"description": "Backup identifier", "type": "string"}, "creation_date": {"description": "Creation date of the backup snapshot", "type": "string", "format": "date-time"}, "size": {"description": "Archive size in bytes", "type": "integer", "format": "int32"}}, "required": ["id", "creation_date", "size"], "examples": [{"id": "UCR2_2023-09-17_145305", "creation_date": "2023-09-17T14:53:05+02:00", "size": 2370274}]}, "BackupMetadataVersion": {"type": "object", "properties": {"backup": {"description": "Version of the backup data model in [SemVer](https://semver.org/) format.", "type": "string"}, "core": {"description": "Core app version", "type": "string"}, "os": {"description": "Operating system version", "type": "string"}}, "required": ["backup"]}, "BackupMetadata": {"type": "object", "properties": {"id": {"description": "Backup identifier", "type": "string"}, "creation_date": {"description": "Creation date of the backup snapshot", "type": "string", "format": "date-time"}, "version": {"$ref": "#/components/schemas/BackupMetadataVersion"}, "report": {"$ref": "#/components/schemas/BackupReport"}}, "required": ["id", "creation_date", "version"], "examples": [{"id": "UCR2_2023-09-17_145305", "creation_date": "2023-09-17T14:53:05+00:00", "version": {"backup": "1.0.0", "core": "0.34.5-beta", "os": "1.2.0"}}]}, "CustomComponent": {"description": "Type of custom component.", "type": "string", "enum": ["ui", "web_configurator"]}, "ReleaseRequirements": {"type": "object", "properties": {"firmware_version": {"description": "[SemVer](https://semver.org/) version requirement, describing the intersection of some version comparators to\nmatch the installed UC Remote firmware.\n\n- `>=1.0`: requires at least version 1.0.0\n- `>=0.9.0, <0.10.0`: only works with minor version 0.9.*   \n\nFollows the Cargo's SemVer support documented in the [Specifying Dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html)\nchapter of the Cargo reference.\n", "type": "string"}}}, "CustomRelease": {"type": "object", "properties": {"name": {"$ref": "#/components/schemas/LanguageText"}, "version": {"type": "string", "maxLength": 40}, "description": {"$ref": "#/components/schemas/LanguageText"}, "developer": {"$ref": "#/components/schemas/DriverDeveloper"}, "home_page": {"description": "Optional home page url for more information.", "type": "string", "format": "uri", "maxLength": 255}, "release_date": {"description": "Release date of the component.", "type": "string", "format": "date"}, "requirements": {"$ref": "#/components/schemas/ReleaseRequirements"}}}, "CustomInstall": {"description": "Information about an installed custom component. The `installed` flag reports if a custom installation", "type": "object", "properties": {"component": {"$ref": "#/components/schemas/CustomComponent"}, "installed": {"description": "Custom component has been installed. When `installed: true` is set, more information is returned in `release`.\n", "type": "boolean"}, "active": {"description": "Custom component is active and replacing the default component.", "type": "boolean"}, "installation_date": {"description": "Installation date of the component. Only provided when `installed: true` is set.", "type": "string", "format": "date-time"}, "release": {"$ref": "#/components/schemas/CustomRelease"}}, "required": ["component", "installed", "active"]}, "SystemLogEntry": {"type": "object", "properties": {"ts": {"description": "Timestamp of log entry", "type": "string", "format": "date-time"}, "service": {"description": "Service identifier", "type": "string"}, "prio": {"description": "Priority, corresponds to [Syslog levels](https://en.wikipedia.org/wiki/Syslog#Severity_level)", "type": "integer"}, "msg": {"description": "Log message", "type": "string"}}}, "SystemLogBoot": {"type": "object", "properties": {"index": {"type": "integer"}, "boot_id": {"description": "Boot identifier usable for querying logs.", "type": "string"}, "first_entry": {"type": "string", "format": "date-time"}, "last_entry": {"type": "string", "format": "date-time"}}}, "SystemLogService": {"type": "object", "properties": {"service": {"description": "Service identifier usable for querying logs.", "type": "string"}, "active": {"description": "Service is active", "type": "boolean"}, "name": {"description": "Human readable service name", "type": "string"}}}, "SystemLogWebAppCfg": {"type": "object", "properties": {"autostart": {"description": "Automatically run web-app after system start", "type": "boolean"}, "enabled": {"description": "State of web-app", "type": "boolean"}, "password": {"description": "Web-app password. The password can only be set and not retrieved.\nAn empty value will disable the password, a missing field doesn't change an existing password.\n", "type": "string", "pattern": "^[\\w*@^(){}\\[\\]:,.=-]{6,30}$"}}}, "PowerMode": {"type": "string", "enum": ["NORMAL", "IDLE", "LOW_POWER", "SUSPEND"]}, "PowerModeResponse": {"type": "object", "properties": {"mode": {"$ref": "#/components/schemas/PowerMode"}, "power_supply": {"description": "A power supply is online, device doesn't enter standby while connected.", "type": "boolean"}, "standby_timeout_sec": {"description": "Time in seconds until the system goes into standby.\nThis is the max value of the regular standby and the longest active standby inhibitor.\n", "type": "integer", "minimum": 0}, "standby_inhibitors": {"description": "There are active standby inhibitors preventing system standby.\n- A blocking inhibitor will return a constant `standby_timeout_sec` value of `86400` (1 day).\n", "type": "boolean"}}, "required": ["mode", "power_supply", "standby_inhibitors"]}, "PowerStatus": {"type": "string", "enum": ["CHARGING", "DISCHARGING", "NOT_CHARGING", "FULL"]}, "BatteryStatusResponse": {"type": "object", "properties": {"capacity": {"description": "Current battery charge in %", "type": "integer", "minimum": 0, "maximum": 100}, "status": {"$ref": "#/components/schemas/PowerStatus"}, "power_supply": {"description": "A power supply is online, device doesn't run on battery.", "type": "boolean"}}, "required": ["capacity", "status"]}, "BatteryCharger": {"type": "object", "properties": {"features": {"type": "array", "items": {"type": "string"}}, "power_supply": {"description": "A power supply is online, device doesn't run on battery.", "type": "boolean"}, "wireless_charging": {"description": "Wireless charging is active. Only returned on devices with wireless charging.", "type": "boolean"}, "wireless_charging_enabled": {"description": "Wireless charging is enabled. Only returned on devices with wireless charging.", "type": "boolean"}}, "required": ["features", "power_supply"]}, "BatteryChargerUpdate": {"type": "object", "properties": {"wireless_charging_enabled": {"description": "Enable or disable wireless charging. Only supported on devices with wireless charging.", "type": "boolean"}}}, "InhibitMode": {"type": "string", "enum": ["BLOCK", "DELAY"]}, "Inhibitor": {"type": "object", "properties": {"id": {"description": "Unique identifier", "type": "string"}, "who": {"description": "A descriptive string who is inhibiting", "type": "string"}, "why": {"description": "A descriptive string why is being inhibited", "type": "string"}, "mode": {"$ref": "#/components/schemas/InhibitMode"}, "delay": {"description": "Delay value in seconds for mode: DELAY", "type": "integer", "minimum": 0}, "created": {"description": "Duration in seconds when this inhibitor was created", "type": "integer", "minimum": 0}}, "required": ["id", "who", "mode"]}, "Inhibitors": {"type": "array", "items": {"$ref": "#/components/schemas/Inhibitor"}}, "CreateStandbyInhibitor": {"type": "object", "properties": {"id": {"description": "Unique identifier, automatically created if not specified.", "type": "string", "minLength": 1, "maxLength": 64}, "who": {"description": "A descriptive string who is inhibiting", "type": "string", "minLength": 1, "maxLength": 64}, "why": {"description": "A descriptive string why is being inhibited", "type": "string", "maxLength": 64}, "delay": {"description": "Delay standby for given seconds, otherwise block indefinitely until inhibitor is removed.", "type": "integer", "minimum": 1}}, "required": ["who"]}, "AmbientLight": {"type": "object", "properties": {"intensity": {"description": "Light intensity. 0 = pitch black, 65535 = very bright.", "type": "integer", "minimum": 0, "maximum": 65535}}, "required": ["intensity"]}, "AvailableSystemUpdate": {"type": "object", "properties": {"id": {"description": "Update identifier", "type": "string"}, "title": {"type": "string"}, "description": {"$ref": "#/components/schemas/LanguageText"}, "version": {"type": "string"}, "channel": {"$ref": "#/components/schemas/UpdateChannel"}, "release_date": {"type": "string", "format": "date"}, "size": {"type": "integer", "format": "int64"}, "release_notes_url": {"type": "string", "format": "uri"}, "download": {"$ref": "#/components/schemas/UpdateDownloadState"}}, "required": ["id", "title", "description", "version", "release_date", "size"]}, "AvailableSystemUpdateResponse": {"type": "object", "properties": {"update_in_progress": {"type": "boolean"}, "last_check_date": {"description": "Last update check timestamp.", "type": "string", "format": "date-time"}, "next_check_date": {"description": "Next scheduled update check timestamp.", "type": "string", "format": "date-time"}, "update_check_enabled": {"type": "boolean"}, "installed_version": {"description": "Installed system version.", "type": "string"}, "available": {"type": "array", "items": {"$ref": "#/components/schemas/AvailableSystemUpdate"}}}, "required": ["update_check_enabled", "installed_version", "available"]}, "SystemUpdateState": {"type": "string", "enum": ["IDLE", "START", "RUN", "SUCCESS", "FAILURE", "DOWNLOAD", "DONE", "SUB_PROCESS", "PROGRESS"]}, "SystemUpdateProgress": {"type": "object", "properties": {"state": {"$ref": "#/components/schemas/SystemUpdateState"}, "update_id": {"description": "Update identifier", "type": "string"}, "download_percent": {"description": "Percent of download", "type": "integer"}, "download_bytes": {"description": "Total of bytes to be downloaded", "type": "integer", "format": "int64"}, "total_steps": {"description": "Total number of update steps", "type": "integer"}, "current_step": {"description": "Current installation step index", "type": "integer"}, "current_percent": {"description": "Percent in current step", "type": "integer"}}, "required": ["state", "update_id"]}, "SystemUpdateResponse": {"type": "object", "properties": {"state": {"$ref": "#/components/schemas/SystemUpdateState"}, "update_id": {"description": "Update identifier", "type": "string"}}, "required": ["state", "update_id"]}, "WpaState": {"description": "- `UNKNOWN`: Unknown state. The driver returned a state which could not be handled.\n- `ERROR`: Error retrieving state information.\n- `DISCONNECTED`: This state indicates that client is not associated, but is likely to start looking for an access point. This state is entered when a connection is lost.\n- `INTERFACE_DISABLED`: This state is entered if the network interface is disabled. The driver refuses any new operations that would use the radio until the interface has been enabled.\n- `INACTIVE`: This state is entered if there are no enabled networks in the configuration. The driver is not trying to associate with a new network and external interaction (e.g. add or enable a network) is needed to start association.\n- `SCANNING`: Scanning for a network.\n- `AUTHENTICATED`: Trying to authenticate with a BSS/SSID.\n- `ASSOCIATING`: Trying to associate with a BSS/SSID.\n- `ASSOCIATED`: Association completed.\n- `FOUR_WAY_HANDSHAKE`: WPA 4-Way Key Handshake in progress.\n- `GROUP_HANDSHAKE`: WPA Group Key Handshake in progress.\n- `COMPLETED`: All authentication completed.\n", "type": "string", "enum": ["UNKNOWN", "ERROR", "DISCONNECTED", "INTERFACE_DISABLED", "INACTIVE", "SCANNING", "AUTHENTICATED", "ASSOCIATING", "ASSOCIATED", "FOUR_WAY_HANDSHAKE", "GROUP_HANDSHAKE", "COMPLETED"]}, "WifiStatus": {"type": "object", "properties": {"bands": {"description": "Available WiFi bands", "type": "array", "items": {"$ref": "#/components/schemas/WifiBand"}}, "wpa_state": {"$ref": "#/components/schemas/WpaState"}, "id": {"description": "Network identifier", "type": "integer"}, "bssid": {"description": "MAC physical address of the access point (basic service set identifier)", "type": "string"}, "ssid": {"description": "Network name (service set identifier)", "type": "string"}, "ssid_hex": {"description": "Hex encoded string of the native SSID byte array.", "type": "string"}, "freq": {"description": "Frequency of the channel in MHz (e.g., 2412 = channel 1)", "type": "integer"}, "address": {"description": "MAC physical address of the WiFi adapter", "type": "string"}, "pairwise_cipher": {"type": "string"}, "group_cipher": {"type": "string"}, "key_mgmt": {"type": "string"}, "ip_address": {"description": "Client IP address", "type": "string"}, "noise": {"description": "Noise level (dBm)", "type": "integer"}, "rssi": {"description": "Signal level (dBm)", "type": "integer"}, "avg_rssi": {"description": "Average RSSI (dBm)", "type": "integer"}, "est_throughput": {"description": "Estimated throughput in kbps", "type": "integer"}, "snr": {"description": "Signal-to-noise ratio in dB", "type": "integer"}, "linkspeed": {"description": "Link speed (Mbps)", "type": "integer"}}, "required": ["wpa_state"]}, "WifiCmd": {"type": "string", "enum": ["DISCONNECT", "RECONNECT", "REASSOCIATE", "ENABLE_ALL_NETWORKS", "DISABLE_ALL_NETWORKS"]}, "AccessPointScan": {"type": "object", "properties": {"bssid": {"description": "MAC physical address of the access point (basic service set identifier)", "type": "string"}, "frequency": {"description": "Frequency of the channel in MHz (e.g., 2412 = channel 1)", "type": "string"}, "signal_level": {"description": "Signal level (dBm)", "type": "integer"}, "auth": {"description": "Authentication method", "type": "string"}, "ssid": {"description": "SSID network name as friendly UTF-8 representation. Use this name to present the network to users, but not for\nadding a new network configuration. This is a lossy conversion from the native SSID byte array.\n", "type": "string"}, "ssid_hex": {"description": "Hex encoded string of the native SSID byte array.\n\nAlways use this representation, when connecting to a network from a scan result.\n", "type": "string"}}, "required": ["bssid", "ssid", "ssid_hex"]}, "ApScanStatus": {"type": "object", "properties": {"active": {"type": "boolean"}, "scan": {"type": "array", "items": {"$ref": "#/components/schemas/AccessPointScan"}}}, "required": ["active", "scan"]}, "NetworkState": {"type": "string", "enum": ["CONNECTED", "OUT_OF_RANGE", "DISABLED", "TEMPORARY_DISABLED"]}, "SavedNetwork": {"description": "A saved network configuration (known network)", "type": "object", "properties": {"id": {"description": "Network identification, used for further operations on this network", "type": "integer"}, "ssid": {"description": "Network name (service set identifier)", "type": "string"}, "ssid_hex": {"description": "Hex encoded string of the native SSID byte array.", "type": "string"}, "secured": {"description": "Secured or unsecured network", "type": "boolean"}, "state": {"$ref": "#/components/schemas/NetworkState"}}, "required": ["id", "ssid", "ssid_hex", "secured"]}, "SavedNetworks": {"type": "array", "items": {"$ref": "#/components/schemas/SavedNetwork"}}, "CreateWifiNetwork": {"type": "object", "properties": {"ssid": {"description": "Network name (service set identifier).\n\nOnly use for valid UTF-8 names, when creating a new configuration and not from a scan result.    \nAlways use `ssid_hex`, when adding a network configuration from a scan result! Otherwise it's not guaranteed,\nthat the correct network is configured. The SSID name can contain non-displayable characters.\n", "type": "string", "minLength": 1, "maxLength": 32}, "ssid_hex": {"description": "Hex encoded string of the native SSID byte array, returned from a network scan.\n", "minLength": 2, "maxLength": 64}, "password": {"type": "string", "minLength": 1, "maxLength": 63}}}, "WifiNetworkCmd": {"type": "string", "enum": ["ENABLE", "DISABLE", "SELECT"]}, "ModifyWifiNetwork": {"type": "object", "properties": {"password": {"type": "string", "minLength": 1, "maxLength": 63}}, "required": ["password"]}, "ActivityId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 36, "description": "Activity identifier"}, "FriendlyName": {"type": "string", "maxLength": 64}, "IrStatus": {"type": "object", "properties": {"dock_id": {"$ref": "#/components/schemas/DockId"}, "learning_active": {"description": "Dock is in IR learning mode", "type": "boolean"}, "state": {"$ref": "#/components/schemas/DockState"}, "codes": {"type": "array", "items": {"$ref": "#/components/schemas/LearnedIrCode"}}}}, "MediaPlayerRepeatMode": {"type": "string", "enum": ["OFF", "ALL", "ONE"]}, "MediaPlayAction": {"description": "The media play action is used to specify how the media item should be played.\n\nNotes:\n- Common values are defined as enum variants. Using these values is recommended, so the UI can show locale aware commands.\n- Integrations can use their custom values, but they might not be available in the UI.\n", "type": "string", "maxLength": 20, "anyOf": [{"enum": ["PLAY_NOW", "PLAY_NEXT", "ADD_TO_QUEUE"]}, {}], "default": "PLAY_NOW"}, "QueueItem": {"description": "\ud83d\udea7 initial draft, do not use!", "type": "object", "properties": {"queue_item_id": {"type": "string", "description": "Unique identifier for the item within this queue instance."}, "media_id": {"type": "string", "description": "Unique identifier for the item (opaque to Core-API)."}, "title": {"type": "string", "description": "Display name."}, "media_class": {"$ref": "#/components/schemas/MediaClass"}, "media_type": {"$ref": "#/components/schemas/MediaContentType"}, "can_browse": {"type": "boolean", "description": "If `true`, the item can be browsed (is a container)."}, "can_play": {"type": "boolean", "description": "If `true`, the item can be played directly."}, "thumbnail": {"type": "string", "description": "URL to download the image, or a base64 encoded data."}, "artist": {"type": "string", "description": "Artist name."}, "album": {"type": "string", "description": "Album name."}, "duration": {"type": "integer", "description": "Duration in seconds."}}, "required": ["queue_item_id", "media_id", "title"]}, "MediaQueueResponse": {"description": "\ud83d\udea7 initial draft, do not use!", "type": "object", "properties": {"items": {"type": "array", "items": {"$ref": "#/components/schemas/QueueItem"}}, "current_index": {"type": "integer", "description": "Absolute index of the currently playing item within the full queue."}}, "required": ["items"]}, "Pages": {"type": "array", "items": {"$ref": "#/components/schemas/Page"}}, "UiId": {"type": "string", "format": "^[a-zA-Z0-9\\-_]+$", "minLength": 1, "maxLength": 36, "description": "Unique user interface identifier."}, "UploadSystemImageResponse": {"type": "object", "properties": {"id": {"description": "Update identifier", "type": "string"}}, "required": ["id"]}, "ActivityRequest": {"$ref": "#/components/schemas/ActivityCreate"}, "AmbientLightResponse": {"$ref": "#/components/schemas/AmbientLight"}}, "responses": {"Err500InternalServerError": {"description": "The server has encountered a situation it does not know how to handle. Retrying the same request will most likely result in the same error.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err400BadRequest": {"description": "The server could not understand the request due to invalid syntax or missing data.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ValidationErrorResponse"}}}}, "Err401Unauthorized": {"description": "Authentication credentials were missing or incorrect. The client must authenticate itself to get the requested response.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err403Forbidden": {"description": "The request is understood, but the client does not have access rights to the content.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err404NotFound": {"description": "The resource does not exist or the URI is invalid.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err422UnprocessableEntity": {"description": "The request was well-formed but cannot be processed. Used for already existing data which cannot be re-created.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "SuccessMessage": {"description": "Successful operation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err507InsufficientStorage": {"description": "There is insufficient storage to store the resource.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err503ServiceUnavailable": {"description": "The server is not ready to handle the request. Try again later.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err409Conflict": {"description": "The request conflicts with the current state of the target resource.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err413PayloadTooLarge": {"description": "Request entity is too large and not supported.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err408RequestTimeout": {"description": "The request timed out.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err415UnsupportedMediaType": {"description": "The media format of the requested data is not supported.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}, "Err429TooManyRequests": {"description": "The client has sent too many requests in a given amount of time.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiResponse"}}}}}, "securitySchemes": {"basicAuth": {"type": "http", "description": "Basic authentication. Please only use for single requests and testing with Swagger / OpenAPI.", "scheme": "basic"}, "cookieAuth": {"type": "apiKey", "description": "Cookie based session authentication. Does not work with Swagger / OpenAPI testing.", "in": "cookie", "name": "id"}}}}