API Overview and Request Patterns

All SmartThings API calls follow consistent conventions for authentication, content types, and rate limiting.

Base URL

All API requests, including OAuth token operations, use the base URL:

https://api.smartthings.com

Authentication

API requests are authenticated with a Bearer token in the Authorization header. The token is the access_token obtained during the OAuth flow.

Authorization: Bearer {access_token}

If the access token has expired, the API returns a 401 Unauthorized response. See Token Management for information on how to refresh tokens.

Request Headers

All API requests should include:

Header	Value	Notes
Authorization	Bearer {access_token}	Required for all API requests
Accept	application/json	Response format
Content-Type	application/json;charset=utf-8	Required for requests with a JSON body (POST, PUT)

Example GET Request

GET https://api.smartthings.com/v1/locations/3269ef1a-xxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Accept: application/json
Authorization: Bearer 68cd394f-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example POST Request

POST https://api.smartthings.com/v1/installedapps/23ad67f8-xxxx-xxxx-xxxx-xxxxxxxxxxxx/subscriptions HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer 68cd394f-xxxx-xxxx-xxxx-xxxxxxxxxxxx

{...request body...}

Rate Limiting

SmartThings enforces rate limits on API calls. Every response includes headers indicating your current rate limit status:

Header	Description
x-ratelimit-limit	Maximum number of requests allowed in the current window
x-ratelimit-remaining	Number of requests remaining in the current window
x-ratelimit-reset	Time in milliseconds until the rate limit window resets

Rate limits vary by endpoint. In most cases, the limit is applied per principal (installed app instance or user for PAT tokens), but some endpoints have limits per device. The following values have been observed:

Endpoint	Limit	Window (seconds)	Entity
GET /v1/locations/{id}	250	60	Principal
GET /v1/installedapps/{id}	200	60	Principal
GET /v1/devices	1000	900	Principal
GET /v1/devices/{id}	400	900	Device
GET /v1/devices/{id}/.../status	350	60	Device
POST /v1/devices/{id}/commands	120	60	Device
POST /v1/installedapps/{id}/subscriptions	60	900	Principal
DELETE /v1/installedapps/{id}/subscriptions	15	900	Principal

When your app exceeds the rate limit, the API returns a 429 Too Many Requests response. Your app should implement backoff logic and respect the x-ratelimit-reset value to determine when to retry.

Response Format

Successful responses return JSON with a 200 status code. List endpoints return items in a paginated structure:

{
 "items": [...],
 "_links": {}
}

Error responses include an appropriate HTTP status code and an error body with details about the failure.

Pagination of Responses

The API limits the number of items returned in a response. If you have more items than the limit, the _links property of the response will include a reference to get the next page of items. For example, if you have more than the maximum page size of devices, you will get a response like this:

{
 "items": [...],
 "_links":
   "next": {
      "href": "https://api.smartthings.com/v1/devices?max=200&page=1&isNext=true"
   }
}

You can specify a smaller max page size if desired, but you cannot exceed the default value.

Not all API endpoints use the same pagination scheme. Note that the devices endpoint is the most likely endpoint to exceed pagination limits.

Up Next

With these conventions understood, proceed to Retrieve Installed App & Location Details to make your first API calls.