{"openapi":"3.1.0","info":{"title":"SmartThings (BYOK) API","version":"0.1.0","description":"SmartThings (BYOK) lets an AI assistant read your own SmartThings data through the SmartThings API with a key you supply (SmartThings personal access token (a new token is valid for 24 hours; give it read scopes only)). Read-only: 10 tools (list_devices, get_device, get_device_status, get_device_health, list_locations, list_rooms, get_current_mode, list_scenes, list_rules, list_installed_apps)....\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-smartthings.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-smartthings/docs"},"termsOfService":"https://connectorbay.com/byok-smartthings/terms"},"servers":[{"url":"https://byok-smartthings.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-smartthings/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/list_devices":{"post":{"operationId":"list_devices","summary":"List the devices you can access with name, label, maker, location, room, type, health state and creation time. Pairing k","description":"List the devices you can access with name, label, maker, location, room, type, health state and creation time. Pairing keys and cipher data are not returned. Use for \"Which SmartThings devices are offline\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only items in this location id.","title":"Location Id"},"capability":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only devices with this capability, for example switch or temperatureMeasurement.","title":"Capability"},"include_health":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include each device's health state.","title":"Include Health"}},"title":"list_devicesArguments","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_device":{"post":{"operationId":"get_device","summary":"Get one device: name, label, maker, location, room, type, health state and creation time. Pairing keys and cipher data a","description":"Get one device: name, label, maker, location, room, type, health state and creation time. Pairing keys and cipher data are not returned. Use for \"Show SmartThings device 6f1b3a5c\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"SmartThings device id (a UUID) from list_devices.","maxLength":64,"title":"Device Id","type":"string"}},"required":["device_id"],"title":"get_deviceArguments","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_device_status":{"post":{"operationId":"get_device_status","summary":"Get the full current status of a device: the value of every capability attribute in each component, plus its health stat","description":"Get the full current status of a device: the value of every capability attribute in each component, plus its health state. Use for \"What is the current state of SmartThings device 6f1b3a5c\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"SmartThings device id (a UUID) from list_devices.","maxLength":64,"title":"Device Id","type":"string"}},"required":["device_id"],"title":"get_device_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/get_device_health":{"post":{"operationId":"get_device_health","summary":"Get whether a device is online or offline and when that last changed. Use for \"Is SmartThings device 6f1b3a5c online\".","description":"Get whether a device is online or offline and when that last changed. Use for \"Is SmartThings device 6f1b3a5c online\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"device_id":{"description":"SmartThings device id (a UUID) from list_devices.","maxLength":64,"title":"Device Id","type":"string"}},"required":["device_id"],"title":"get_device_healthArguments","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/list_locations":{"post":{"operationId":"list_locations","summary":"List your locations (homes) with id and name. Use for \"Which SmartThings locations do I have\".","description":"List your locations (homes) with id and name. Use for \"Which SmartThings locations do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many locations to return.","title":"Limit"}},"title":"list_locationsArguments","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/list_rooms":{"post":{"operationId":"list_rooms","summary":"List the rooms of a location with id, name and dates. Use for \"Which rooms are in my SmartThings home\".","description":"List the rooms of a location with id, name and dates. Use for \"Which rooms are in my SmartThings home\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"SmartThings location id (a UUID) from list_locations.","maxLength":64,"title":"Location Id","type":"string"}},"required":["location_id"],"title":"list_roomsArguments","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_current_mode":{"post":{"operationId":"get_current_mode","summary":"Get the current mode of a location (for example Home, Away or Night). Use for \"What mode is my SmartThings home in\".","description":"Get the current mode of a location (for example Home, Away or Night). Use for \"What mode is my SmartThings home in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"SmartThings location id (a UUID) from list_locations.","maxLength":64,"title":"Location Id","type":"string"}},"required":["location_id"],"title":"get_current_modeArguments","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/list_scenes":{"post":{"operationId":"list_scenes","summary":"List scenes with name, location and creation, update and last run times. Use for \"Which SmartThings scenes do I have\".","description":"List scenes with name, location and creation, update and last run times. Use for \"Which SmartThings scenes do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only items in this location id.","title":"Location Id"}},"title":"list_scenesArguments","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/list_rules":{"post":{"operationId":"list_rules","summary":"List automation rules of a location with name, status (Enabled or Disabled), where they run and dates. Use for \"Which Sm","description":"List automation rules of a location with name, status (Enabled or Disabled), where they run and dates. Use for \"Which SmartThings automations are enabled\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"description":"Location id to list rules for.","maxLength":64,"title":"Location Id","type":"string"}},"required":["location_id"],"title":"list_rulesArguments","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/list_installed_apps":{"post":{"operationId":"list_installed_apps","summary":"List installed apps and integrations with name, type, status, location and update time. Use for \"Which apps are installe","description":"List installed apps and integrations with name, type, status, location and update time. Use for \"Which apps are installed in my SmartThings account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location_id":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only items in this location id.","title":"Location Id"},"status":{"anyOf":[{"enum":["PENDING","AUTHORIZED","REVOKED","DISABLED"],"type":"string"},{"type":"null"}],"default":null,"description":"Only apps in this state.","title":"Status"},"app_type":{"anyOf":[{"enum":["LAMBDA_SMART_APP","WEBHOOK_SMART_APP"],"type":"string"},{"type":"null"}],"default":null,"description":"Only apps of this type.","title":"App Type"}},"title":"list_installed_appsArguments","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}}}}