Ring API Hello World

Get started with the Ring Partner API — explore device APIs from your terminal and stream live video in your browser.

What's Inside

Path	What it does	You need
`scripts/`	Python scripts to call Ring APIs from your terminal	Python 3.8+ and a token
`app/`	Next.js web app with live video streaming and real-time event dashboard	Node.js 18+ and a token

🚀 Coming from the Ring Developer Playground?

You already have a token — jump straight to:

Explore APIs from your terminal → (Python, no web app needed)

Live stream in your browser → (Node.js, one command)

Step 1: Get Your Token

Go to the Ring Developer Playground
Click Generate Token
Copy the access token

The Playground gives you a short-lived access token (~30 minutes) that works with all Ring APIs. No app registration, OAuth setup, or client credentials needed — just the token.

Note: When the token expires, return to the Playground and generate a fresh one.

Step 2: Explore APIs (Python Scripts)

Call any Ring API directly from your terminal. Each script is a self-contained code snippet you can copy into your own project.

Setup

cd scripts
pip install -r requirements.txt

Usage

Run the interactive explorer:

python explore_apis.py --token "eyJ..."

This shows a menu where you pick which API to call:

=== Ring API Explorer ===
Use your token to call any Ring API.

1. List Devices
2. Device Status
3. Device Capabilities
4. Device Location
5. Device Configurations
6. Event History
7. User Profile
8. Run All
0. Exit

Select an API to call:

Or run individual scripts directly:

# List all your devices
python list_devices.py --token "eyJ..."

# Check if a device is online
python device_status.py --token "eyJ..." --device-id "ava1.ring.device.XXX"

# Get device capabilities (video codecs, motion detection, etc.)
python device_capabilities.py --token "eyJ..." --device-id "ava1.ring.device.XXX"

# Get device location (country/state)
python device_location.py --token "eyJ..." --device-id "ava1.ring.device.XXX"

# Get device configurations (motion zones, privacy zones)
python device_configurations.py --token "eyJ..." --device-id "ava1.ring.device.XXX"

# Get event history (motion events, doorbell presses, live views)
python event_history.py --token "eyJ..." --device-id "ava1.ring.device.XXX"

# Get your user profile
python user_profile.py --token "eyJ..."

Tip: If you don't pass --device-id, scripts that need one will auto-discover your first device.

Each script prints the equivalent curl command so you can copy it into Postman, your own code, or any HTTP client:

→ GET https://api.amazonvision.com/v1/devices
  curl -X GET "https://api.amazonvision.com/v1/devices" \
    -H "Authorization: Bearer $TOKEN"

Available Scripts

Script	API Endpoint	Description
`list_devices.py`	`GET /v1/devices`	List all accessible devices
`device_status.py`	`GET /v1/devices/{id}/status`	Check if device is online/offline
`device_capabilities.py`	`GET /v1/devices/{id}/capabilities`	Video codecs, motion detection, image enhancements
`device_location.py`	`GET /v1/devices/{id}/location`	Country and state (for compliance)
`device_configurations.py`	`GET /v1/devices/{id}/configurations`	Motion zones, privacy zones, image settings
`event_history.py`	`GET /v1/history/devices/{id}/events`	Past motion, doorbell, and live view events
`user_profile.py`	`GET /v1/users/me`	Your Ring account ID, name, and email
`explore_apis.py`	All of the above	Interactive menu to call any API

Step 3: Live Video Stream (Web App)

Stream live video from a Ring device directly in your browser using WebRTC.

Setup

# Install dependencies
npm install

# Create your environment file
cp .env.example .env.local

Edit .env.local and paste your token from Step 1:

RING_ACCESS_TOKEN=eyJ...paste_your_token_here

Run

npm run dev

Open http://localhost:3000 in your browser.

The app will:

Auto-discover devices associated with your token
Show a Start Live Stream button
Click it to begin a WebRTC live video stream from your Ring device

When the token expires, paste a fresh one from the Playground into .env.local and restart the server.

Advanced: Full Dashboard (Refresh Token Mode)

For production integrations with long-lived sessions, the app supports OAuth refresh tokens with auto-renewal. This mode shows the full dashboard including webhook events, video processors, and canvas overlays.

Setup

RING_REFRESH_TOKEN=your_refresh_token_here
RING_CLIENT_ID=your_client_id_here
RING_CLIENT_SECRET=your_client_secret_here

All three variables are required. The app automatically refreshes the access token when it expires.

See Authentication for how to obtain refresh tokens through the OAuth account linking flow, and Configure Your Ring Application for how to get your client credentials.

Device ID (Optional)

NEXT_PUBLIC_RING_DEVICE_ID=your_device_id_here

If set, the app uses this device directly instead of auto-discovering.

Important

Do not set both RING_ACCESS_TOKEN and RING_REFRESH_TOKEN — the app will show a configuration error. Use one or the other.

Environment Variables

Variable	Description	Required
`RING_ACCESS_TOKEN`	Access token from the Playground	Yes (if not using refresh token)
`RING_REFRESH_TOKEN`	OAuth refresh token from account linking	Yes (if not using access token)
`RING_CLIENT_ID`	OAuth client ID from app registration	Yes (only with refresh token)
`RING_CLIENT_SECRET`	OAuth client secret from app registration	Yes (only with refresh token)
`NEXT_PUBLIC_RING_DEVICE_ID`	Device ID (skips auto-discovery)	No
`NEXT_PUBLIC_RING_DEVICE_NAME`	Display name for the device	No
`RING_WEBHOOK_SECRET`	Bearer token for webhook auth	No

Features

Access Token Mode (Playground)

Live Video Streaming — WebRTC-based low-latency video from Ring devices
Auto Device Discovery — Automatically finds devices linked to your token
Simplified UI — Full-screen live view, no distractions

Refresh Token Mode (Production)

Everything above, plus:
Webhook Events — Real-time SSE for Ring camera webhooks (motion, doorbell, etc.)
Video Processors — Plugin system for real-time video analysis
Hand Tracking Game — Catch-the-box game using MediaPipe hand detection
Canvas Overlays — Bounding boxes, heatmaps, and visual effects

Architecture

scripts/
├── explore_apis.py            # Interactive API explorer
├── list_devices.py            # GET /v1/devices
├── device_status.py           # GET /v1/devices/{id}/status
├── device_capabilities.py     # GET /v1/devices/{id}/capabilities
├── device_location.py         # GET /v1/devices/{id}/location
├── device_configurations.py   # GET /v1/devices/{id}/configurations
├── event_history.py           # GET /v1/history/devices/{id}/events
├── user_profile.py            # GET /v1/users/me
└── requirements.txt           # Python dependencies

app/
├── page.tsx                   # Main dashboard
├── components/                # UI components
├── hooks/
│   ├── useWebRTCStream.ts     # WebRTC connection management
│   ├── useEventStream.ts      # SSE with auto-reconnect
│   └── useCanvasOverlay.ts    # Optimized render loop
└── api/
    ├── webhook/               # Webhook receiver + SSE endpoint
    └── ring/                  # Ring API integration
        ├── config/            # Auth mode detection
        ├── devices/           # Device discovery + status
        ├── stream/            # WebRTC WHEP live streaming
        ├── events/            # Event history
        └── token/             # Token info

lib/
├── auth.ts                    # Token management (access token / refresh token)
├── video-processors/          # Plugin system for video analysis
├── schemas/                   # Zod validation schemas
└── sse-broadcast.ts           # SSE client management

Video Processors

Built-in processors (available in refresh token mode):

Processor	Description
🎯 Catch the Logo	Hand-tracking game with fire effects
🌡️ Motion Heatmap	Visualizes motion as color overlay
💡 Brightness Analyzer	Analyzes frame brightness levels

Creating Custom Processors

import {VideoProcessor, ProcessorResult} from './types';
import {processorRegistry} from './registry';

class MyProcessor implements VideoProcessor {
  id = 'my-processor';
  name = 'My Processor';
  description = 'Does something cool';
  enabled = false;

  async process(
    frame: ImageData,
    canvas: HTMLCanvasElement,
    video: HTMLVideoElement,
  ): Promise<ProcessorResult | null> {
    return {
      id: `my-${Date.now()}`,
      processorId: this.id,
      timestamp: Date.now(),
      data: {},
      boundingBoxes: [{x: 0, y: 0, width: 100, height: 100, label: 'Detected'}],
    };
  }
}

processorRegistry.register(new MyProcessor());

See docs/video-processors.md for the complete guide.

Webhook Integration

Available in refresh token mode. The dashboard receives webhook events via POST and broadcasts them to connected clients via SSE.

# Send a test event
curl -X POST http://localhost:3000/api/webhook \
  -H "Content-Type: application/json" \
  -d '{"event_type": "motion_detected", "device_id": "camera-1"}'

Configure your Ring webhook to POST to /api/webhook. Set RING_WEBHOOK_SECRET in .env.local for authentication.

API Reference

For full API documentation:

Tech Stack

Scripts: Python 3.8+ with requests
Web App: Next.js 14 (App Router), TypeScript, Tailwind CSS
Video: WebRTC (WHEP protocol), MediaPipe Hands
Validation: Zod
Events: Server-Sent Events (SSE)

Development

# Run web app with hot reload
npm run dev

# Type checking
npx tsc --noEmit

# Build for production
npm run build

License

MIT

GeezerVison

Latest commit

History

Folders and files

Repository files navigation

Ring API Hello World

What's Inside

Step 1: Get Your Token

Step 2: Explore APIs (Python Scripts)

Setup

Usage

Available Scripts

Step 3: Live Video Stream (Web App)

Setup

Run

Advanced: Full Dashboard (Refresh Token Mode)

Setup

Device ID (Optional)

Important

Environment Variables

Features

Access Token Mode (Playground)

Refresh Token Mode (Production)

Architecture

Video Processors

Creating Custom Processors

Webhook Integration

API Reference

Tech Stack

Development

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages