Developer API

"Batteries included" software to build custom tools for your hardware ecosystem

Getting Started

The Electric Home Hub API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL 
https://api.electrichomehub.com/v1

Authentication

Authenticate your API requests by including your secret API key in the Authorization header. You can manage your API keys from the Electric Home Hub Dashboard.

Example Request 
curl https://api.electrichomehub.com/v1/devices \
  -H "Authorization: Bearer ehk_live_51bf5e..."

SDK Downloads

JavaScript SDK

Full-featured SDK for web applications

Python SDK

Comprehensive Python library

REST Documentation

Complete API reference

Core Resources

Devices

The Device object represents electric hardware in your system. Use these endpoints to manage your device inventory, track warranties, and monitor status.

GET /api/devices

Retrieve all devices for the authenticated user

Example Request 
curl https://api.electrichomehub.com/v1/devices \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json"
Response 
{
  "data": [
    {
      "id": "device_123",
      "name": "Smart Thermostat",
      "manufacturer": "Nest",
      "model": "T3007ES",
      "status": "active",
      "warranty_expiry": "2025-12-31",
      "location": "Living Room",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}
POST /api/devices

Add a new device to the system

Example Request 
curl https://api.electrichomehub.com/v1/devices \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smart Refrigerator",
    "manufacturer": "Samsung",
    "model": "RF28R7351SR",
    "serial_number": "ABC123456",
    "warranty_expiry": "2026-06-15",
    "location": "Kitchen"
  }'
Response 
{
  "id": "device_456",
  "name": "Smart Refrigerator",
  "manufacturer": "Samsung",
  "model": "RF28R7351SR",
  "serial_number": "ABC123456",
  "warranty_expiry": "2026-06-15",
  "location": "Kitchen",
  "status": "active",
  "created_at": "2024-12-29T10:30:00Z"
}
PUT /api/devices/{id}

Update an existing device

Example Request 
curl -X PUT https://api.electrichomehub.com/v1/devices/device_123 \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smart Refrigerator Pro",
    "location": "Updated Kitchen",
    "warranty_expiry": "2026-12-31"
  }'
Response 
{
  "id": "device_123",
  "name": "Smart Refrigerator Pro",
  "manufacturer": "Samsung",
  "model": "RF28R7351SR",
  "location": "Updated Kitchen",
  "warranty_expiry": "2026-12-31",
  "updated_at": "2024-12-29T10:30:00Z"
}
DELETE /api/devices/{id}

Remove a device from the system

Example Request 
curl -X DELETE https://api.electrichomehub.com/v1/devices/device_123 \
  -H "Authorization: Bearer ehk_live_51bf5e..."
Response 
{
  "message": "Device successfully deleted",
  "deleted_id": "device_123"
}

Document Management

GET /api/documents

List all documents with optional filtering

Example Request 
curl https://api.electrichomehub.com/v1/documents?category=Manual&device_id=device_123 \
  -H "Authorization: Bearer ehk_live_51bf5e..."
Response 
{
  "documents": [
    {
      "id": "doc_456",
      "name": "Smart Refrigerator Manual",
      "device_id": "device_123",
      "category": "Manual",
      "file_type": "pdf",
      "file_size": 2457600,
      "upload_date": "2024-12-15T09:00:00Z",
      "download_url": "/api/documents/doc_456/download"
    }
  ],
  "total": 1,
  "page": 1
}
POST /api/documents

Upload a new document

Example Request 
curl https://api.electrichomehub.com/v1/documents \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -F "file=@thermostat_manual.pdf" \
  -F "name=Thermostat Installation Guide" \
  -F "category=Manual" \
  -F "device_id=device_789"
Response 
{
  "id": "doc_790",
  "name": "Thermostat Installation Guide",
  "device_id": "device_789",
  "category": "Manual",
  "file_type": "pdf",
  "file_size": 1024000,
  "upload_date": "2024-12-29T10:35:00Z",
  "message": "Document uploaded successfully"
}
GET /api/documents/{id}/download

Download a specific document

GET /api/documents/doc_456/download

// Response
Content-Type: application/pdf
Content-Disposition: attachment; filename="manual.pdf"
[Binary file content]
DELETE /api/documents/{id}

Delete a document

DELETE /api/documents/doc_456

// Response
{
  "message": "Document successfully deleted",
  "deleted_id": "doc_456"
}

Alert Management

GET /api/alerts

Retrieve system alerts with filtering options 

GET /api/alerts?severity=critical&status=unread&limit=10

// Response
{
  "alerts": [
    {
      "id": "alert_123",
      "device_id": "device_456",
      "title": "Safety Recall Notice",
      "description": "Refrigerator recall due to potential fire hazard",
      "severity": "critical",
      "type": "recall",
      "status": "unread",
      "created_at": "2024-12-29T08:00:00Z",
      "actions": [
        {
          "type": "contact_manufacturer",
          "label": "Contact Samsung",
          "url": "https://samsung.com/recall"
        }
      ]
    }
  ],
  "total": 1,
  "unread_count": 3
}
POST /api/alerts/{id}/acknowledge

Mark an alert as acknowledged

POST /api/alerts/alert_123/acknowledge

// Response
{
  "id": "alert_123",
  "status": "acknowledged",
  "acknowledged_at": "2024-12-29T10:45:00Z",
  "message": "Alert marked as acknowledged"
}
POST /api/alerts

Create a custom alert

POST /api/alerts
{
  "device_id": "device_789",
  "title": "Maintenance Reminder",
  "description": "Annual HVAC filter replacement due",
  "severity": "info",
  "type": "maintenance",
  "scheduled_date": "2025-01-15T00:00:00Z"
}

// Response
{
  "id": "alert_124",
  "device_id": "device_789", 
  "title": "Maintenance Reminder",
  "severity": "info",
  "status": "scheduled",
  "created_at": "2024-12-29T10:50:00Z"
}
GET /api/alerts/stats

Get alert statistics and summary

GET /api/alerts/stats

// Response
{
  "total_alerts": 15,
  "unread_count": 3,
  "by_severity": {
    "critical": 1,
    "warning": 5,
    "info": 9
  },
  "by_type": {
    "recall": 1,
    "firmware_update": 4,
    "warranty": 6,
    "maintenance": 4
  },
  "recent_activity": "2024-12-29T08:00:00Z"
}

User Management

The User object represents an end user with their profile, preferences, and proficiency levels. Essential for personalizing the electric home experience.

GET /api/users/{id}

Retrieve user profile and preferences

Example Request 
curl https://api.electrichomehub.com/v1/users/user_123 \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json"
Response 
{
  "id": "user_123",
  "email": "john@example.com",
  "name": "John Smith",
  "proficiency_level": "intermediate",
  "preferences": {
    "notification_frequency": "daily",
    "energy_monitoring": true,
    "auto_maintenance_reminders": true
  },
  "subscription_tier": "pro",
  "homes": ["home_456"],
  "created_at": "2024-01-15T10:30:00Z",
  "last_active": "2024-12-29T10:00:00Z"
}
PUT /api/users/{id}/proficiency

Update user proficiency level for personalized recommendations

Example Request 
curl https://api.electrichomehub.com/v1/users/user_123/proficiency \
  -X PUT \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json" \
  -d '{
    "proficiency_level": "advanced",
    "skills": ["electrical_basics", "smart_home_automation", "energy_optimization"]
  }'

Home Management

The Home object represents a physical location containing electric devices. Enables location-based device grouping and home-specific analytics.

GET /api/homes

List all homes for the authenticated user

Example Request 
curl https://api.electrichomehub.com/v1/homes \
  -H "Authorization: Bearer ehk_live_51bf5e..."
Response 
{
  "homes": [
    {
      "id": "home_456",
      "name": "Main Residence",
      "address": "123 Electric Ave, Smart City, SC 12345",
      "type": "single_family",
      "square_footage": 2500,
      "built_year": 2018,
      "device_count": 12,
      "energy_profile": {
        "monthly_usage_kwh": 850,
        "solar_generation_kwh": 320,
        "efficiency_score": 87
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1
}
POST /api/homes

Create a new home profile

Example Request 
curl https://api.electrichomehub.com/v1/homes \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vacation Home",
    "address": "456 Lake View Dr, Mountain View, CA 94041",
    "type": "vacation_home",
    "square_footage": 1800,
    "built_year": 2020
  }'
GET /api/homes/{id}/analytics

Get comprehensive home energy and device analytics

Response 
{
  "energy_insights": {
    "efficiency_trend": "improving",
    "cost_savings_month": 45.23,
    "carbon_footprint_reduction": "12%"
  },
  "device_health": {
    "optimal_performance": 8,
    "needs_attention": 2,
    "maintenance_due": 2
  },
  "benchmarks": {
    "vs_similar_homes": "15% more efficient",
    "vs_neighborhood_avg": "8% above average"
  },
  "recommendations": [
    {
      "type": "energy_optimization",
      "description": "Optimize HVAC scheduling for 12% additional savings",
      "potential_savings": "$28/month"
    }
  ]
}

Marketplace Services

Access to curated electric home services including hardware recommendations, trial programs, educational content, and professional maintenance services.

GET /api/marketplace/hardware-recommendations

Get personalized hardware recommendations based on home profile

Example Request 
curl https://api.electrichomehub.com/v1/marketplace/hardware-recommendations \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -d "home_id=home_456&category=energy_storage&budget_max=15000"
Response 
{
  "recommendations": [
    {
      "id": "rec_789",
      "device_type": "home_battery",
      "model": "Tesla Powerwall 3",
      "manufacturer": "Tesla",
      "price_estimate": "$14,500",
      "compatibility_score": 95,
      "roi_estimate": "7.2 years",
      "benefits": ["backup_power", "time_of_use_optimization", "solar_integration"],
      "trial_available": true,
      "professional_install_required": true
    }
  ],
  "total_matches": 3,
  "personalization_factors": ["home_size", "existing_solar", "usage_patterns"]
}
POST /api/marketplace/trial-requests

Request hardware trial service for evaluation

Example Request 
curl https://api.electrichomehub.com/v1/marketplace/trial-requests \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json" \
  -d '{
    "device_model": "Tesla Powerwall 3",
    "home_id": "home_456",
    "trial_duration_days": 30,
    "installation_preference": "professional",
    "evaluation_goals": ["backup_power_testing", "cost_analysis", "integration_compatibility"]
  }'
Response 
{
  "trial_id": "trial_456",
  "status": "approved",
  "device_model": "Tesla Powerwall 3",
  "trial_duration_days": 30,
  "installation_date": "2025-01-15",
  "monthly_trial_cost": "$299",
  "includes": ["device_rental", "professional_installation", "monitoring", "support"],
  "evaluation_dashboard_url": "/trials/trial_456/dashboard"
}
GET /api/marketplace/educational-content

Access personalized educational content and benchmarking data

Example Request 
curl https://api.electrichomehub.com/v1/marketplace/educational-content \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -d "user_proficiency=intermediate&home_type=single_family&focus_area=energy_optimization"
Response 
{
  "recommended_content": [
    {
      "id": "content_123",
      "title": "Advanced Energy Storage Strategies",
      "type": "video_course",
      "duration_minutes": 45,
      "difficulty": "intermediate",
      "topics": ["battery_sizing", "time_of_use_optimization", "grid_tie_benefits"],
      "completion_rate": "89%",
      "user_rating": 4.7
    }
  ],
  "benchmarking_data": {
    "your_efficiency_percentile": 78,
    "neighborhood_comparison": "+12% above average",
    "improvement_potential": "18% with recommended upgrades"
  },
  "learning_path": {
    "current_level": "intermediate",
    "next_milestone": "energy_expert",
    "progress_percentage": 65
  }
}
POST /api/marketplace/maintenance-services

Schedule professional maintenance and upgrade services

Example Request 
curl https://api.electrichomehub.com/v1/marketplace/maintenance-services \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json" \
  -d '{
    "service_type": "preventive_maintenance",
    "device_ids": ["device_123", "device_456"],
    "home_id": "home_456",
    "preferred_date": "2025-02-15",
    "service_level": "comprehensive",
    "includes_upgrade_consultation": true
  }'
Response 
{
  "service_request_id": "service_789",
  "status": "scheduled",
  "technician": {
    "name": "Sarah Johnson",
    "certification": "Certified Electric Home Specialist",
    "rating": 4.9,
    "specialties": ["solar_systems", "battery_storage", "smart_home_integration"]
  },
  "scheduled_date": "2025-02-15T09:00:00Z",
  "estimated_duration": "3 hours",
  "service_cost": "$299",
  "includes": ["device_inspection", "performance_optimization", "upgrade_recommendations", "warranty_updates"]
}
GET /api/marketplace/offers

Get personalized offers based on user profile and home data

Response 
{
  "offers": [
    {
      "id": "offer_123",
      "type": "hardware_upgrade_bundle",
      "title": "Complete Energy Independence Package",
      "description": "Solar + Battery + Smart Controls for maximum efficiency",
      "value": "$2,500 savings",
      "valid_until": "2025-03-31T23:59:59Z",
      "personalization_score": 92,
      "includes": ["15% discount", "free_installation", "extended_warranty", "monitoring_service"]
    },
    {
      "id": "offer_124",
      "type": "educational_subscription",
      "title": "Energy Expert Masterclass Bundle",
      "description": "Advanced courses + 1-on-1 consultation + community access",
      "value": "First month free",
      "valid_until": "2025-02-15T23:59:59Z",
      "target_proficiency": "intermediate_to_advanced"
    }
  ],
  "total_potential_savings": "$3,200",
  "recommendation_confidence": "high"
}

Webhooks

Electric Home Hub can send webhook events that notify your application when certain events happen in your account. Webhooks are useful for building event-driven applications.

Managing Webhooks

POST /api/webhooks

Create a webhook endpoint to receive events

Example Request 
curl https://api.electrichomehub.com/v1/webhooks \
  -H "Authorization: Bearer ehk_live_51bf5e..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my/webhook/endpoint",
    "events": ["device.created", "alert.critical", "warranty.expiring"],
    "description": "Production webhook for device monitoring"
  }'
GET /api/webhooks

List all webhook endpoints

Response 
{
  "data": [
    {
      "id": "we_1NKy7GFKjGRL3KI7",
      "object": "webhook_endpoint",
      "url": "https://example.com/my/webhook/endpoint",
      "enabled_events": ["device.created", "alert.critical"],
      "status": "enabled",
      "created": 1677533967
    }
  ]
}

Event Types

device.created - Occurs when a new device is added
device.updated - Occurs when device information changes
alert.critical - Occurs when a critical alert is generated
warranty.expiring - Occurs when a warranty is expiring soon

Webhooks

Subscribe to real-time events and notifications from Electric Home Hub

POST /api/webhooks

Create a new webhook subscription

POST /api/webhooks
{
  "url": "https://your-app.com/webhooks/electric-home-hub",
  "events": ["device.created", "alert.critical", "warranty.expiring"],
  "description": "Production webhook for device monitoring"
}

// Response
{
  "id": "webhook_456",
  "url": "https://your-app.com/webhooks/electric-home-hub",
  "events": ["device.created", "alert.critical", "warranty.expiring"],
  "secret": "whsec_1234567890abcdef",
  "created_at": "2024-12-29T11:00:00Z",
  "status": "active"
}

Webhook Events

device.created - New device added
device.updated - Device information changed
device.deleted - Device removed
alert.critical - Critical alert triggered
alert.created - New alert generated
warranty.expiring - Warranty expiring soon
document.uploaded - New document added

Webhook Payload Example

{
  "id": "evt_789",
  "event": "alert.critical",
  "created_at": "2024-12-29T11:15:00Z",
  "data": {
    "alert": {
      "id": "alert_123",
      "device_id": "device_456",
      "title": "Safety Recall Notice",
      "severity": "critical",
      "type": "recall",
      "description": "Refrigerator recall due to potential fire hazard"
    },
    "device": {
      "id": "device_456",
      "name": "Smart Refrigerator",
      "manufacturer": "Samsung",
      "model": "RF28R7351SR"
    }
  }
}

Error Handling

Electric Home Hub API uses conventional HTTP response codes and returns error details in JSON format.

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "Invalid device data provided",
    "details": [
      {
        "field": "warranty_expiry", 
        "message": "Date must be in ISO 8601 format"
      }
    ],
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

200 OK - Request successful
201 Created - Resource created successfully
400 Bad Request - Invalid request data
401 Unauthorized - Invalid API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Advanced Examples

Bulk Device Import

POST /api/devices/bulk
{
  "devices": [
    {
      "name": "Smart TV",
      "manufacturer": "LG",
      "model": "OLED55C1PUB",
      "category": "Entertainment",
      "warranty_expiry": "2025-06-01"
    },
    {
      "name": "Coffee Maker",
      "manufacturer": "Keurig",
      "model": "K-Elite",
      "category": "Appliances", 
      "warranty_expiry": "2025-03-15"
    }
  ]
}

// Response
{
  "imported": 2,
  "failed": 0,
  "devices": [
    {"id": "device_101", "name": "Smart TV"},
    {"id": "device_102", "name": "Coffee Maker"}
  ]
}

Search Across All Data

GET /api/search?q=samsung&include=devices,documents,alerts

// Response
{
  "query": "samsung",
  "results": {
    "devices": [
      {
        "id": "device_123",
        "name": "Smart Refrigerator",
        "manufacturer": "Samsung",
        "relevance": 0.95
      }
    ],
    "documents": [
      {
        "id": "doc_456", 
        "name": "Samsung RF28R7351SR Manual",
        "relevance": 0.87
      }
    ],
    "alerts": [
      {
        "id": "alert_789",
        "title": "Samsung Refrigerator Recall",
        "relevance": 0.92
      }
    ]
  },
  "total_results": 3
}

Export Data

POST /api/export
{
  "format": "csv",
  "include": ["devices", "documents"],
  "filters": {
    "device_category": "Appliances",
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    }
  }
}

// Response
{
  "export_id": "exp_456",
  "status": "processing", 
  "download_url": null,
  "estimated_completion": "2024-12-29T11:25:00Z"
}

// Check export status
GET /api/export/exp_456

{
  "export_id": "exp_456",
  "status": "completed",
  "download_url": "https://api.electrichomehub.com/exports/exp_456.csv",
  "expires_at": "2024-12-30T11:20:00Z"
}

Authentication

All API requests require authentication using your API key in the Authorization header: 

Authorization: Bearer YOUR_API_KEY

Complete Example Request

curl -X GET \
  "https://api.electrichomehub.com/v1/devices" \
  -H "Authorization: Bearer ehk_prod_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp/1.0"

// JavaScript Example
const response = await fetch('https://api.electrichomehub.com/v1/devices', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ehk_prod_1234567890abcdef',
    'Content-Type': 'application/json'
  }
});

const devices = await response.json();

// Python Example  
import requests

headers = {
    'Authorization': 'Bearer ehk_prod_1234567890abcdef',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.electrichomehub.com/v1/devices',
    headers=headers
)

devices = response.json()

Rate Limiting

Free Plan: 100 requests/hour
Developer Plan: 1,000 requests/hour
Professional Plan: 5,000 requests/hour
Enterprise Plan: 25,000 requests/hour

Rate limit headers included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200