Console

Settings

Sign out

Notifications

Alexa

Amazon Appstore

Ring

AWS

Documentation

Support

My Cases

Console

Ring Docs

Ring

Device Discovery

After obtaining customer authentication materials, partners can access Ring's public API to discover and interact with shared devices. Device discovery is the entry point for accessing Ring resources.

Overview

Device discovery follows the JSON:API Specification and provides:

Basic device information and identification
Device capabilities and supported features
Current device status and connectivity
Location information (coarse-grained)
User configurations and settings

Basic Device Discovery

Retrieve a list of devices accessible to the authenticated user:

GET https://api.amazonvision.com/v1/devices
Authorization: Bearer <access_token>

Response Structure

{
  "meta": {
    "time": "2026-02-14T22:57:16Z"
  },
  "data": [
    {
      "type": "devices",
      "id": "ava1.ring.device.XXXYYY",
      "attributes": {
        "name": "Front Door Camera"
      },
      "relationships": {
        "status": {
          "data": {
            "type": "device-status",
            "id": "ava1.ring.device.status.XXXYYY"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/status"
          }
        },
        "capabilities": {
          "data": {
            "type": "device-capabilities",
            "id": "ava1.ring.device.capabilities.XXXYYY"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/capabilities"
          }
        },
        "configurations": {
          "data": {
            "type": "device-configurations",
            "id": "ava1.ring.device.configurations.XXXYYY"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/configurations"
          }
        },
        "location": {
          "data": {
            "type": "locations",
            "id": "5ecd04ff-3d93-4a6e-80e4-035f735a58e4"
          },
          "links": {
            "related": "/v1/devices/ava1.ring.device.XXXYYY/location"
          }
        }
      }
    }
  ]
}

Response Fields

Field	Type	Description
`meta.time`	string	ISO 8601 timestamp of the response
`data`	array	Array of device resources
`data[].type`	string	Always `"devices"`
`data[].id`	string	Unique device identifier (e.g., `ava1.ring.device.XXXYYY`) — use this in all device-specific API calls
`data[].attributes.name`	string	User-assigned device name (e.g., "Front Door Camera")
`data[].relationships`	object	JSON:API resource linkage — each relationship contains `data` (type + id) and `links` (API path)

Note: Device IDs are opaque strings (e.g., ava1.ring.device.GPBGLFYKSWL2...). Do not parse or make assumptions about their structure — use them as-is in API paths.

Use the include query parameter to fetch related data in a single request:

GET https://api.amazonvision.com/v1/devices?include=status,capabilities
Authorization: Bearer <access_token>

Response with Included Data (Compound Document)

When using ?include=status,capabilities, the related resources are returned in a top-level included array. Match resources using the type + id pair from relationships.{rel}.data to the corresponding entry in included:

{
  "meta": {
    "time": "2026-02-14T22:57:16Z"
  },
  "data": [
    {
      "type": "devices",
      "id": "ava1.ring.device.XXXYYY",
      "attributes": {
        "name": "Office"
      },
      "relationships": {
        "status": {
          "data": { "type": "device-status", "id": "ava1.ring.device.status.XXXYYY" },
          "links": { "related": "/v1/devices/ava1.ring.device.XXXYYY/status" }
        },
        "capabilities": {
          "data": { "type": "device-capabilities", "id": "ava1.ring.device.capabilities.XXXYYY" },
          "links": { "related": "/v1/devices/ava1.ring.device.XXXYYY/capabilities" }
        }
      }
    }
  ],
  "included": [
    {
      "type": "device-status",
      "id": "ava1.ring.device.status.XXXYYY",
      "attributes": {
        "online": true
      }
    },
    {
      "type": "device-capabilities",
      "id": "ava1.ring.device.capabilities.XXXYYY",
      "attributes": {
        "video": {
          "configurations": ["resolution_mode"],
          "codecs": ["AVC"],
          "ratio": "16:9",
          "max_resolution": 1080,
          "supported_resolutions": [1080]
        },
        "motion_detection": {
          "configurations": ["enabled", "motion_zones"]
        },
        "image_enhancements": {
          "configurations": ["color_night_vision", "hdr", "ir_led_night_vision", "privacy_zones"]
        }
      }
    }
  ]
}

Note: How ?include= works: Resources requested via include appear in the top-level included array. Resources NOT requested still appear in relationships with data and links but are not embedded in included — use the links.related path to fetch them individually. You can include any combination: status, capabilities, location, configurations.

Included Resource Fields

Included Type	Key Attributes	Description
`device-status`	`online` (boolean)	Whether the device is currently online
`device-capabilities`	`video`, `motion_detection`, `image_enhancements`	Device feature support — codecs, resolutions, configurable settings
`device-configurations`	`motion_detection`, `image_enhancements`	Current user settings — zones, enhancements. See Configurations
`locations`	Coarse location data	Country/state-level location. See Locations

Device Relationships

Each device provides relationships to:

Status: Online/offline state and connectivity — see Status
Capabilities: Supported features and hardware specs — see Capabilities
Location: Coarse geographic information — see Locations
Configurations: User settings and preferences — see Configurations

JSON:API Compliance

The device discovery API follows JSON:API specifications:

Consistent resource structure with type, id, attributes, relationships
Resource linkage via data objects (type + id) in relationships
Compound documents via include parameter with top-level included array
Relationship links for individual resource fetching
Extensible attribute model for future enhancements

Rate Limiting

Respect rate limits (don't exceed 100 TPS)
Implement exponential backoff for retries
Cache device information when appropriate

Sub-pages

Capabilities — Device hardware features and supported functionality
Status — Real-time device availability and connectivity
Locations — Coarse geographic information for compliance
Configurations — User settings, motion zones, and privacy zones

Next: Notifications →