API Documentation

Introduction

The SolarMind API provides developers with powerful tools to integrate our AI-driven solar energy optimization into custom applications, IoT devices, or enterprise systems. Our RESTful API enables real-time access to energy forecasts, optimization controls, usage analytics, and device management.

Base URL: https://api.solarmind.space/v1
Authentication: Bearer Token (JWT) or API Key
Rate Limits: 100 requests/minute (free tier), customizable for enterprise

All endpoints return JSON responses. Error responses follow standard HTTP codes with detailed messages.

Authentication

Authenticate requests using either an API key or OAuth 2.0 bearer token.

API Key

Authorization: Api-Key YOUR_API_KEY

OAuth 2.0

Obtain a token via the /auth endpoint:

POST /auth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

Use the token in headers: Authorization: Bearer YOUR_TOKEN

Core Endpoints

Energy Forecast

Retrieve 72-hour solar production and consumption predictions.

GET /forecast?site_id=12345&period=72h

Parameters:

• site_id (required): Your installation ID
• period (optional): 24h, 48h, 72h (default 72h)
• detail (optional): low/medium/high (default medium)

Response Example:

{
  "forecast": [
    {
      "timestamp": "2025-12-17T12:00:00Z",
      "production_kwh": 5.2,
      "consumption_kwh": 3.8,
      "confidence": 0.92
    }
  ],
  "summary": {
    "total_production": 120.5,
    "self_consumption_rate": 0.88
  }
}

Optimization Control

POST /optimize

Request Body:

{
  "site_id": "12345",
  "devices": ["battery-1", "ev-charger"],
  "mode": "max_savings",
  "duration_hours": 24
}

Response:

{
  "status": "scheduled",
  "job_id": "opt-67890",
  "estimated_savings": 45.20
}

Usage Analytics

GET /analytics?site_id=12345&start=2025-12-01&end=2025-12-17&granularity=day

Parameters:

• site_id (required)
• start/end (required): ISO dates
• granularity (optional): hour/day/week/month