{"openapi":"3.1.0","info":{"title":"Shelly Cloud (BYOK) API","version":"0.1.0","description":"Shelly Cloud (BYOK) lets an AI assistant read your own Shelly Cloud devices and, with your approval of each change, change their state through the Shelly Cloud API with a key you supply (Shelly Cloud authorization key (User settings, Authorization cloud key)). Read tools plus 4 device-changing tools (set_switch, set_light_power, set_light_white, set_light_color); each change runs only when...\n\nMost operations are read-only. These change the state of a device and run only with confirm = \"yes\" after the user approved that change: set_switch, set_light_power, set_light_white, set_light_color. The same tools are available over MCP (streamable HTTP) at https://byok-shelly-cloud-control.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-shelly-cloud-control/docs"},"termsOfService":"https://connectorbay.com/byok-shelly-cloud-control/terms"},"servers":[{"url":"https://byok-shelly-cloud-control.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-shelly-cloud-control/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_device_info":{"post":{"operationId":"get_device_info","summary":"Get the basic record of one Shelly device: id, type, model code, generation and whether it is online. Limited to one cal","description":"Get the basic record of one Shelly device: id, type, model code, generation and whether it is online. Limited to one call per second. Use for \"Is my Shelly device b48a0a1cd978 online\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server":{"description":"Your Shelly Cloud server name, the first part of the Server URI shown next to the authorization key in the Shelly Cloud app (for example shelly-59-eu).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Server","type":"string"},"device_id":{"description":"Shelly device id (hex, for example b48a0a1cd978) from the Shelly Cloud app: Device, Settings, Device Information.","maxLength":40,"title":"Device Id","type":"string"}},"required":["server","device_id"],"title":"get_device_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_component_status":{"post":{"operationId":"get_component_status","summary":"Get the status of one component of a Shelly device, for example switch:0 (output, power, voltage, energy), light:0, inpu","description":"Get the status of one component of a Shelly device, for example switch:0 (output, power, voltage, energy), light:0, input:0, temperature:0 or sys. Limited to one call per second. Use for \"What is the power draw of switch:0 on my Shelly device b48a0a1cd978\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server":{"description":"Your Shelly Cloud server name, the first part of the Server URI shown next to the authorization key in the Shelly Cloud app (for example shelly-59-eu).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Server","type":"string"},"device_id":{"description":"Shelly device id (hex, for example b48a0a1cd978) from the Shelly Cloud app: Device, Settings, Device Information.","maxLength":40,"title":"Device Id","type":"string"},"component":{"description":"Top-level status property to return, for example switch:0, light:0, input:0, temperature:0, em:0 or sys.","maxLength":40,"title":"Component","type":"string"}},"required":["server","device_id","component"],"title":"get_component_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/set_switch":{"post":{"operationId":"set_switch","summary":"Switch one relay channel of a Shelly relay or plug on or off, optionally switching back after a number of seconds. Use o","description":"Switch one relay channel of a Shelly relay or plug on or off, optionally switching back after a number of seconds. Use only for lamps, plugs and similar loads; do not use it for a door, gate, lock, alarm, boiler or gas appliance. This changes the physical device. Use for \"Turn off the Shelly plug b48a0a1cd978\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server":{"description":"Your Shelly Cloud server name, the first part of the Server URI shown next to the authorization key in the Shelly Cloud app (for example shelly-59-eu).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Server","type":"string"},"device_id":{"description":"Shelly device id (hex, for example b48a0a1cd978) from the Shelly Cloud app: Device, Settings, Device Information.","maxLength":40,"title":"Device Id","type":"string"},"on":{"description":"True to switch the output on, false to switch it off.","title":"On","type":"boolean"},"confirm":{"const":"yes","description":"Must be exactly yes, only after the user approved this change in chat.","title":"Confirm","type":"string"},"channel":{"anyOf":[{"maximum":7,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Output channel of the device, starting at 0 (default 0).","title":"Channel"},"toggle_after":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"After this many seconds, switch back to the opposite state. Leave empty for no automatic switch-back.","title":"Toggle After"}},"required":["server","device_id","on","confirm"],"title":"set_switchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":false,"x-changes-device-state":true,"x-requires-confirmation":"confirm"}},"/v1/tools/set_light_power":{"post":{"operationId":"set_light_power","summary":"Switch one channel of a Shelly light or dimmer on or off, optionally switching back after a number of seconds. Use only ","description":"Switch one channel of a Shelly light or dimmer on or off, optionally switching back after a number of seconds. Use only for lamps, plugs and similar loads; do not use it for a door, gate, lock, alarm, boiler or gas appliance. This changes the physical device. Use for \"Turn on the Shelly light b48a0a1cd978\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server":{"description":"Your Shelly Cloud server name, the first part of the Server URI shown next to the authorization key in the Shelly Cloud app (for example shelly-59-eu).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Server","type":"string"},"device_id":{"description":"Shelly device id (hex, for example b48a0a1cd978) from the Shelly Cloud app: Device, Settings, Device Information.","maxLength":40,"title":"Device Id","type":"string"},"on":{"description":"True to switch the light on, false to switch it off.","title":"On","type":"boolean"},"confirm":{"const":"yes","description":"Must be exactly yes, only after the user approved this change in chat.","title":"Confirm","type":"string"},"channel":{"anyOf":[{"maximum":7,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Output channel of the device, starting at 0 (default 0).","title":"Channel"},"toggle_after":{"anyOf":[{"maximum":86400,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"After this many seconds, switch back to the opposite state. Leave empty for no automatic switch-back.","title":"Toggle After"}},"required":["server","device_id","on","confirm"],"title":"set_light_powerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":false,"x-changes-device-state":true,"x-requires-confirmation":"confirm"}},"/v1/tools/set_light_white":{"post":{"operationId":"set_light_white","summary":"Put a Shelly light in white mode with a brightness and an optional color temperature. Use only for lamps, plugs and simi","description":"Put a Shelly light in white mode with a brightness and an optional color temperature. Use only for lamps, plugs and similar loads; do not use it for a door, gate, lock, alarm, boiler or gas appliance. This changes the physical device. Use for \"Set my Shelly bulb b48a0a1cd978 to 50 percent warm white\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server":{"description":"Your Shelly Cloud server name, the first part of the Server URI shown next to the authorization key in the Shelly Cloud app (for example shelly-59-eu).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Server","type":"string"},"device_id":{"description":"Shelly device id (hex, for example b48a0a1cd978) from the Shelly Cloud app: Device, Settings, Device Information.","maxLength":40,"title":"Device Id","type":"string"},"brightness":{"description":"Brightness in percent, 0 to 100.","maximum":100,"minimum":0,"title":"Brightness","type":"integer"},"confirm":{"const":"yes","description":"Must be exactly yes, only after the user approved this change in chat.","title":"Confirm","type":"string"},"channel":{"anyOf":[{"maximum":7,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Output channel of the device, starting at 0 (default 0).","title":"Channel"},"temperature":{"anyOf":[{"maximum":7000,"minimum":2700,"type":"integer"},{"type":"null"}],"default":null,"description":"White color temperature in kelvin, 2700 to 7000, for devices that support it. Leave empty to keep it.","title":"Temperature"},"on":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to also switch the light on, false to switch it off. Leave empty to keep the power state.","title":"On"}},"required":["server","device_id","brightness","confirm"],"title":"set_light_whiteArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":false,"x-changes-device-state":true,"x-requires-confirmation":"confirm"}},"/v1/tools/set_light_color":{"post":{"operationId":"set_light_color","summary":"Put a Shelly RGB light in color mode with red, green and blue values and an optional gain. Use only for lamps, plugs and","description":"Put a Shelly RGB light in color mode with red, green and blue values and an optional gain. Use only for lamps, plugs and similar loads; do not use it for a door, gate, lock, alarm, boiler or gas appliance. This changes the physical device. Use for \"Make my Shelly RGBW light b48a0a1cd978 green\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"server":{"description":"Your Shelly Cloud server name, the first part of the Server URI shown next to the authorization key in the Shelly Cloud app (for example shelly-59-eu).","maxLength":200,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$","title":"Server","type":"string"},"device_id":{"description":"Shelly device id (hex, for example b48a0a1cd978) from the Shelly Cloud app: Device, Settings, Device Information.","maxLength":40,"title":"Device Id","type":"string"},"red":{"description":"Red value, 0 to 255.","maximum":255,"minimum":0,"title":"Red","type":"integer"},"green":{"description":"Green value, 0 to 255.","maximum":255,"minimum":0,"title":"Green","type":"integer"},"blue":{"description":"Blue value, 0 to 255.","maximum":255,"minimum":0,"title":"Blue","type":"integer"},"confirm":{"const":"yes","description":"Must be exactly yes, only after the user approved this change in chat.","title":"Confirm","type":"string"},"channel":{"anyOf":[{"maximum":7,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Output channel of the device, starting at 0 (default 0).","title":"Channel"},"gain":{"anyOf":[{"maximum":100,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Color gain (overall color brightness) in percent, 0 to 100. Leave empty to keep it.","title":"Gain"},"on":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to also switch the light on, false to switch it off. Leave empty to keep the power state.","title":"On"}},"required":["server","device_id","red","green","blue","confirm"],"title":"set_light_colorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":false,"x-changes-device-state":true,"x-requires-confirmation":"confirm"}}}}