{
  "openapi": "3.0.3",
  "info": {
    "title": "Solar API",
    "version": "1.0",
    "description": "Public read-only live data of PV plants Hotel Raj, Wellness Raj and FVE TD SL. Data refreshed every 60 s from Solinteg Cloud."
  },
  "servers": [
    {
      "url": "https://solar.hotelraj.eu/api/v1"
    }
  ],
  "paths": {
    "/plants": {
      "get": {
        "summary": "Current state of all plants",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Plant"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Data not yet available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plants/{id}": {
      "get": {
        "summary": "Current state of one plant",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "hotel-raj",
                "wellness-raj",
                "fve-tdsl"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Plant"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Data not yet available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/plants/{id}/history": {
      "get": {
        "summary": "Per-minute power history",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "hotel-raj",
                "wellness-raj",
                "fve-tdsl"
              ]
            }
          },
          {
            "name": "hours",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 168,
              "default": 24
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "plant_id": {
                          "type": "string"
                        },
                        "hours": {
                          "type": "integer"
                        },
                        "interval_s": {
                          "type": "integer"
                        },
                        "points": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "t": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "pv": {
                                "type": "number",
                                "nullable": true
                              },
                              "grid": {
                                "type": "number",
                                "nullable": true
                              },
                              "battery": {
                                "type": "number",
                                "nullable": true
                              },
                              "load": {
                                "type": "number",
                                "nullable": true
                              },
                              "soc": {
                                "type": "number",
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Plant": {
        "type": "object",
        "required": [
          "id",
          "name",
          "status",
          "power_kw"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "hotel-raj",
              "wellness-raj",
              "fve-tdsl"
            ]
          },
          "name": {
            "type": "string"
          },
          "capacity_kwp": {
            "type": "number"
          },
          "status": {
            "type": "string",
            "enum": [
              "online",
              "partial",
              "offline",
              "stale"
            ]
          },
          "data_quality": {
            "type": "string",
            "enum": [
              "ok",
              "suspect"
            ]
          },
          "data_quality_notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "measured_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "fetched_at": {
            "type": "string",
            "format": "date-time"
          },
          "power_kw": {
            "type": "object",
            "properties": {
              "pv": {
                "type": "number",
                "nullable": true,
                "description": "PV power, kW"
              },
              "grid": {
                "type": "number",
                "nullable": true,
                "description": "Grid power, kW; >0 export, <0 import; null if data_quality != ok"
              },
              "battery": {
                "type": "number",
                "nullable": true,
                "description": "Battery power, kW; >0 discharge, <0 charge"
              },
              "load": {
                "type": "number",
                "nullable": true,
                "description": "Consumption = pv + battery - grid, kW; null if data_quality != ok"
              }
            }
          },
          "battery_soc_pct": {
            "type": "number",
            "nullable": true,
            "description": "Battery state of charge, %"
          },
          "energy_today_kwh": {
            "type": "object",
            "properties": {
              "pv": {
                "type": "number",
                "nullable": true
              },
              "grid_import": {
                "type": "number",
                "nullable": true
              },
              "grid_export": {
                "type": "number",
                "nullable": true
              },
              "battery_charge": {
                "type": "number",
                "nullable": true
              },
              "battery_discharge": {
                "type": "number",
                "nullable": true
              }
            }
          },
          "devices": {
            "type": "object",
            "properties": {
              "online": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "api_version": {
            "type": "string"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "refresh_interval_s": {
            "type": "integer"
          },
          "units": {
            "type": "object"
          },
          "sign_convention": {
            "type": "object"
          },
          "source": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "documentation": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}