Create a Personal Access Token (PAT) at developer.smartthings.com with the required scopes (r:devices:*, x:devices:*, r:scenes:*, x:scenes:*); include the token as Authorization: Bearer <PAT> on all requests to https://api.smartthings.com/v1
List devices with GET /v1/devices; each device object includes deviceId, name, and a components array; retrieve current status with GET /v1/devices/<deviceId>/status to see all component and capability values
Send a command with POST /v1/devices/<deviceId>/commands with body {"commands":[{"component":"main","capability":"switch","command":"on","arguments":[]}]}; check the capability name and supported commands from the device's presentation
List scenes with GET /v1/scenes?locationId=<locationId> and execute a scene with POST /v1/scenes/<sceneId>/execute; scenes set multiple devices to target states atomically
Create a SmartApp webhook subscription to receive real-time device events: register a publicly accessible HTTPS endpoint, implement the CONFIRMATION lifecycle to echo the challenge, and handle the EVENT lifecycle to process device state changes
For subscriptions, POST /v1/installedapps/<installedAppId>/subscriptions with {"sourceType":"CAPABILITY","capability":{"locationId":"<id>","capability":"switch","subscriptionName":"switchSub"}} to subscribe to capability events
Known gotchas
Personal Access Tokens are convenient for testing but are not suitable for multi-user or production integrations; OAuth 2.0 SmartApps with per-user authorization are required when your app accesses devices owned by other users
The SmartThings API enforces rate limits per token; bursting many commands in a loop will return 429 responses — implement request queuing with a small delay between commands
Webhook SmartApps must respond to lifecycle events (PING, CONFIRMATION, EVENT, INSTALL, UPDATE, UNINSTALL) within 10 seconds; slow or missing responses cause the platform to retry and eventually disable the webhook
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp