Device Configurations

Device configurations provide details about user-specified settings that may affect partner processing of video content and device behavior. These settings are particularly important for motion detection and privacy considerations.

Accessing Configuration Data

Configuration information can be retrieved in two ways:

During device discovery using the include parameter:

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

Individual device configurations:

GET https://api.amazonvision.com/v1/devices/{device_id}/configurations
Authorization: Bearer <access_token>

Response Structure

{
  "meta": {
    "time": "2026-02-14T23:37:48Z"
  },
  "data": {
    "type": "device-configurations",
    "id": "ava1.ring.device.configurations.XXXYYY",
    "attributes": {
      "motion_detection": {
        "enabled": "on",
        "motion_zones": [
          {
            "id": "a9d225a6-3122-4f4d-a933-0c24e53cc535",
            "vertices": [
              {"x": 0, "y": 0.2},
              {"x": 0.5, "y": 0.2},
              {"x": 1, "y": 0.2},
              {"x": 1, "y": 0.6},
              {"x": 1, "y": 1},
              {"x": 0.5, "y": 1},
              {"x": 0, "y": 1},
              {"x": 0, "y": 0.6}
            ]
          }
        ]
      },
      "image_enhancements": {
        "color_night_vision": "off",
        "hdr": "off",
        "ir_led_night_vision": "off",
        "auto_zoom_track": "off",
        "privacy_zones": []
      }
    }
  }
}

Note: Privacy zones use the same structure as motion zones (array of objects with id and vertices). When no privacy zones are configured, the array is empty ([]).

Configuration Categories

Motion Detection

enabled: Motion detection on/off status ("on" or "off")
motion_zones: Array of defined motion detection areas
- Each zone has a UUID id and vertices array
- Vertices define the polygon boundaries of the detection zone

Image Enhancements

color_night_vision: Color night vision setting ("on" or "off")
hdr: High Dynamic Range setting ("on" or "off")
ir_led_night_vision: Infrared LED night vision setting ("on" or "off")
auto_zoom_track: Automatic zoom and tracking setting ("on" or "off")
privacy_zones: Array of privacy zones that should be obscured (same structure as motion zones)

Zone Coordinate System

Zones use a normalized coordinate system where all values are in the range 0.0 to 1.0:

Origin: Top-left corner (0, 0)
X-axis: 0.0 = left edge, 1.0 = right edge
Y-axis: 0.0 = top edge, 1.0 = bottom edge
Vertices: Define polygon boundaries as ordered points

To convert to pixel coordinates, multiply by the frame dimensions:

pixel_x = vertex['x'] * frame_width
pixel_y = vertex['y'] * frame_height

Warning: Mixed numeric types in JSON: Vertex x and y values are JSON numbers. When a value falls on a whole number (e.g., 0, 1), JSON parsers may deserialize it as an Integer rather than a Double. In Java, do not cast vertex values directly to (Double) — use ((Number) value).doubleValue() instead. In Python, this is not an issue.

Impact on Partner Operations

Motion Detection Settings

def should_process_motion_events(device_config):
    motion_config = device_config.get('attributes', {}).get('motion_detection', {})
    return motion_config.get('enabled') == 'on'

def get_motion_zones(device_config):
    motion_config = device_config.get('attributes', {}).get('motion_detection', {})
    return motion_config.get('motion_zones', [])

Privacy Zone Handling

def get_privacy_zones(device_config):
    image_config = device_config.get('attributes', {}).get('image_enhancements', {})
    return image_config.get('privacy_zones', [])

def should_obscure_regions(device_config):
    privacy_zones = get_privacy_zones(device_config)
    return len(privacy_zones) > 0

Example Zone Processing

def point_in_polygon(point, vertices):
    """Check if a normalized point (0-1 range) is inside a polygon."""
    x, y = point
    n = len(vertices)
    inside = False
    
    p1x, p1y = vertices[0]['x'], vertices[0]['y']
    for i in range(1, n + 1):
        p2x, p2y = vertices[i % n]['x'], vertices[i % n]['y']
        if y > min(p1y, p2y):
            if y <= max(p1y, p2y):
                if x <= max(p1x, p2x):
                    if p1y != p2y:
                        xinters = (y - p1y) * (p2x - p1x) / (p2y - p1y) + p1x
                    if p1x == p2x or x <= xinters:
                        inside = not inside
        p1x, p1y = p2x, p2y
    
    return inside

Best Practices

Respect privacy zones: Always obscure or avoid processing areas marked as privacy zones
Check motion settings: Verify motion detection is enabled before expecting motion events
Handle missing configs: Not all devices will have all configuration options
Zone processing: Implement proper polygon intersection algorithms for zone handling
Configuration changes: Be prepared for configurations to change over time
Numeric type safety: Always handle vertex coordinates as Number (not Double or Integer) to avoid type cast errors