API Reference

This section provides a comprehensive reference for all Ring Partner API endpoints, including request/response formats, parameters, and examples.

Base URL

All API requests should be made to:

https://api.amazonvision.com

Authentication

All API requests require authentication using OAuth 2.0 Bearer tokens:

Authorization: Bearer <access_token>

Rate Limiting

• Default rate: 100 requests per second (TPS) per partner
• Scope: Rate limits apply per partner client_id across all endpoints

Rate Limit Headers

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests. Use exponential backoff starting at 1 second and respect the Retry-After header.

Content Types

• JSON APIs: application/json
• Media streaming: application/sdp
• Media downloads: Binary content with appropriate MIME types

Authentication Endpoints

Exchange Authorization Code

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
client_id=<partner_client_id>
code=<authorization_code>
client_secret=<partner_client_secret>

Response:

{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Refresh Access Token

POST https://oauth.ring.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token=<refresh_token>
client_id=<partner_client_id>
client_secret=<partner_client_secret>

Response:

{
  "access_token": "xxxxx",
  "refresh_token": "yyyyy",
  "scope": "<scope>",
  "expires_in": 14400,
  "token_type": "Bearer"
}

Endpoint Reference

All device and media endpoints require Authorization: Bearer <access_token>. Responses follow JSON:API format.

Device Endpoints

Media Endpoints

Account & Integration Endpoints

Webhook Events

Partners receive webhook notifications at their configured endpoint. All webhooks include an HMAC-SHA256 signature in the X-Signature header. See Notifications for full details.

Event Types

Error Responses

All errors follow JSON:API format. See Error Handling for comprehensive details.

Common Error Codes

• 400: Bad Request — Invalid parameters
• 401: Unauthorized — Invalid or expired token
• 403: Forbidden — Insufficient permissions
• 404: Not Found — Resource not found
• 429: Too Many Requests — Rate limit exceeded
• 500: Internal Server Error
• 503: Service Unavailable — Device offline

Testing Your Integration

Recommended Tools

There is no official Ring Partner SDK. Use standard HTTP libraries and tools:

Testing with curl

curl -X GET 'https://api.amazonvision.com/v1/devices?include=status,capabilities' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -v

SDKs and Libraries

There is no official Ring Partner SDK. Use standard HTTP libraries:

JavaScript/TypeScript

const response = await fetch('https://api.amazonvision.com/v1/devices', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  }
});
const devices = await response.json();

Python

import requests

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}
response = requests.get('https://api.amazonvision.com/v1/devices', headers=headers)
devices = response.json()