{"definitions":{"Login":{"properties":{"password":{"description":"The user's password","example":"SecretPass123","format":"password","type":"string"},"username":{"description":"The username of the account","example":"alice","type":"string"}},"required":["username","password"]},"Measurements":{"properties":{"measurements":{"description":"List of installation measurement blocks","items":{"properties":{"installation_code":{"description":"Installation identifier","example":"12345","type":"string"},"values":{"description":"Timestamped measurements","items":{"properties":{"timestamp":{"description":"UTC timestamp (ISO8601)","example":"2025-09-19T10:00:00Z","format":"date-time","type":"string"},"value":{"description":"Measurement value","example":152.7,"format":"float","type":"number"},"variable_name":{"description":"P = active power (kW) Q = reactive power (kvar)\n","enum":["P","Q"],"example":"P","type":"string"}},"required":["timestamp","variable_name","value"],"type":"object"},"type":"array"}},"required":["installation_code","values"],"type":"object"},"type":"array"}},"required":["measurements"]},"PatchInstallationStatus":{"properties":{"installation_code":{"description":"Unique identifier of the installation to update","example":"inst_001","type":"string"},"is_active":{"description":"New active status: - 1 → active - 0 → inactive\n","enum":[0,1],"example":1,"type":"integer"}},"required":["installation_code","is_active"]},"RegisterInstallation":{"properties":{"country":{"description":"Country where the installation is located","enum":["portugal","spain","france"],"example":"portugal","type":"string"},"forecast_algorithm":{"description":"Forecast algorithm reference","enum":["lqr","default"],"example":"default","type":"string"},"generation":{"description":"Installed generation capacity (MW or kW depending on type)","example":500,"format":"float","type":"number"},"installation_code":{"description":"Unique installation identifier","example":"inst_001","type":"string"},"installation_type":{"description":"Type of installation","enum":["load","wind","solar"],"example":"solar","type":"string"},"is_active":{"description":"Installation status: - 1 → active - 0 → inactive\n","enum":[0,1],"example":1,"type":"integer"},"latitude":{"description":"Latitude of installation","example":41.1579,"format":"float","type":"number"},"longitude":{"description":"Longitude of installation","example":-8.6291,"format":"float","type":"number"},"net_power_types":{"description":"Power types measured at the installation","example":["P","Q"],"items":{"enum":["P","Q"],"type":"string"},"type":"array"},"source_nwp":{"description":"NWP source provider","example":"meteogalicia","type":"string"}},"required":["installation_code","country","generation","installation_type","latitude","longitude","net_power_types","source_nwp","is_active","forecast_algorithm"]},"RegisterUser":{"properties":{"description":{"description":"Optional description or user information","example":"Energy operator account","type":"string"},"password":{"description":"Plain-text password to be hashed before storage","example":"MySecurePassword123","format":"password","type":"string"},"permissions":{"description":"Permission level assigned to the user","enum":["none","basic","intermediate","advanced","admin"],"example":"intermediate","type":"string"},"username":{"description":"Unique username for the new account","example":"newuser","type":"string"}},"required":["username","password"]},"ResetPassword":{"properties":{"new_password":{"description":"The new password to assign to the account","example":"NewSecret456","format":"password","type":"string"},"old_password":{"description":"The current password of the user","example":"OldSecret123","format":"password","type":"string"},"username":{"description":"Username of the account to reset","example":"alice","type":"string"}},"required":["username","old_password","new_password"]},"UpdateUserPermission":{"properties":{"cod_restriction":{"description":"Optional code restriction to apply","example":"GRID-001","type":"string"},"permissions":{"description":"New permission level for the user","enum":["none","basic","intermediate","advanced","admin"],"example":"advanced","type":"string"},"username":{"description":"The username whose permissions will be updated","example":"jane","type":"string"}},"required":["username","permissions"]}},"info":{"description":"powered by Flasgger","termsOfService":"/tos","title":"A swagger API","version":"0.0.1"},"paths":{"/api/forecast/get-forecast":{"get":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"description":"Start date (ISO8601 format) of the forecast window.","in":"query","name":"start_date","required":true,"schema":{"format":"date-time","type":"string"}},{"description":"End date (ISO8601 format) of the forecast window.","in":"query","name":"end_date","required":true,"schema":{"format":"date-time","type":"string"}},{"description":"Comma-separated list of quantiles to retrieve. Defaults to \"50\".\n","in":"query","name":"quantiles","required":false,"schema":{"example":"10,50,90","type":"string"}},{"description":"Comma-separated list of installation codes. If omitted, all installations are returned.\n","in":"query","name":"installation_code","required":false,"schema":{"type":"string"}},{"description":"Register type: - \"P\" for active power (kW) - \"Q\" for reactive power (kvar) - Empty string for both. Defaults to empty.\n","in":"query","name":"register_type","required":false,"schema":{"enum":["P","Q",""],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"code":1,"data":[{"forecasts":[{"installation_code":"12345","installation_type":"LV","values":[{"computed_at":"2025-09-19T09:55:00Z","quantile":"10","timestamp":"2025-09-19T10:00:00Z","units":"kW","value":120.5,"variable_name":"P"}]}]}]}}},"description":"Forecast data successfully retrieved"},"400":{"content":{"application/json":{"example":{"code":0,"message":"Field 'register_type' must be either 'P' or 'Q'"}}},"description":"Invalid or missing parameters"},"401":{"content":{"application/json":{"example":{"code":0,"message":"Invalid token."}}},"description":"Unauthorized (invalid token)"},"500":{"content":{"application/json":{"example":{"code":0,"message":"Internal Server Error."}}},"description":"Internal server error"}},"summary":"Retrieve forecast data from the database","tags":["Forecast"]}},"/api/forecast/kpi":{"get":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"description":"Date (ISO8601 format) for which KPIs should be retrieved.\n","in":"query","name":"request_day","required":true,"schema":{"format":"date-time","type":"string"}},{"description":"Comma-separated list of installation codes. If omitted, KPIs for all installations are returned.\n","in":"query","name":"installation_code","required":false,"schema":{"type":"string"}},{"description":"Register type: - \"P\" for active power (kW) - \"Q\" for reactive power (kvar) - Empty string for both (default).\n","in":"query","name":"register_type","required":false,"schema":{"enum":["P","Q",""],"type":"string"}},{"description":"Time horizon for KPIs: - \"short\" → based on last 2 weeks of forecasts - \"long\" → based on last year of forecasts (default).\n","in":"query","name":"term","required":false,"schema":{"default":"long","enum":["short","long"],"type":"string"}},{"description":"Comma-separated list of metrics to return. Supported: `crps`, `mae`, `nmae`, `rmse`, `nrmse`. Defaults to all.\n","in":"query","name":"metrics","required":false,"schema":{"example":"mae,rmse","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"code":1,"data":[{"kpis":[{"installation_code":"12345","installation_type":"LV","values":[{"horizon":1,"mae":12.5,"nmae":0.07,"nrmse":0.09,"rmse":15.2,"variable_name":"P"},{"horizon":1,"mae":8.1,"nmae":0.05,"nrmse":0.06,"rmse":10.3,"variable_name":"Q"}]}]}]}}},"description":"KPIs successfully retrieved"},"400":{"content":{"application/json":{"example":{"code":0,"message":"Field 'term' must be either 'short' or 'long'"}}},"description":"Invalid or missing parameters"},"401":{"content":{"application/json":{"example":{"code":0,"message":"Invalid token."}}},"description":"Unauthorized (invalid token)"},"500":{"content":{"application/json":{"example":{"code":0,"message":"Internal Server Error."}}},"description":"Internal server error"}},"summary":"Retrieve Key Performance Indicators (KPIs) for installations","tags":["KPIs"]}},"/api/forecast/measurements":{"get":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"description":"Start date (ISO8601 format) of the measurements window.","in":"query","name":"start_date","required":true,"schema":{"format":"date-time","type":"string"}},{"description":"End date (ISO8601 format) of the measurements window.","in":"query","name":"end_date","required":true,"schema":{"format":"date-time","type":"string"}},{"description":"Comma-separated list of installation codes.   If omitted, measurements for all installations are returned.\n","in":"query","name":"installation_code","required":false,"schema":{"type":"string"}},{"description":"Register type:   - \"P\" → active power (kW)   - \"Q\" → reactive power (kvar)   - Empty string for both (default).\n","in":"query","name":"register_type","required":false,"schema":{"enum":["P","Q",""],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"code":1,"data":[{"measurements":[{"installation_code":"12345","installation_type":"LV","values":[{"timestamp":"2025-09-19T10:00:00Z","units":"kW","value":153.7,"variable_name":"P"},{"timestamp":"2025-09-19T10:05:00Z","units":"kW","value":149.2,"variable_name":"P"}]},{"installation_code":"67890","installation_type":"LV","values":[{"timestamp":"2025-09-19T10:00:00Z","units":"kvar","value":72.5,"variable_name":"Q"}]}]}]}}},"description":"Measurements successfully retrieved"},"400":{"content":{"application/json":{"example":{"code":0,"message":"Field 'register_type' must be either 'P' or 'Q'"}}},"description":"Invalid or missing parameters"},"401":{"content":{"application/json":{"example":{"code":0,"message":"Invalid token."}}},"description":"Unauthorized (invalid token)"},"500":{"content":{"application/json":{"example":{"code":0,"message":"Internal Server Error."}}},"description":"Internal server error"}},"summary":"Retrieve measurements data from the database","tags":["Measurements"]},"post":{"parameters":[{"description":"Bearer JWT token with at least `advanced` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/Measurements"}}],"responses":{"201":{"description":"Measurements accepted","schema":{"properties":{"code":{"example":1,"type":"integer"},"message":{"example":"ok","type":"string"}},"type":"object"}},"400":{"description":"Invalid request body","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"'measurements' is a required property","type":"string"}},"type":"object"}},"401":{"description":"Unauthorized (invalid or missing token)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Invalid token.","type":"string"}},"type":"object"}},"500":{"description":"Internal server error","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Internal Server Error.","type":"string"}},"type":"object"}}},"summary":"Submit new measurements for one or more installations","tags":["Measurements"]}},"/api/installations/info":{"get":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"description":"Comma-separated list of installation codes.   If omitted, metadata for all installations is returned.\n","in":"query","name":"installation_code","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"code":1,"data":[{"installations":[{"installation_code":"12345","installation_type":"LV","last_updated":"2025-09-19T08:00:00Z","location":"Downtown","owner":"ACME Corp"},{"installation_code":"67890","installation_type":"MV","last_updated":"2025-09-18T14:30:00Z","location":"Uptown","owner":"EnergyCo"}]}]}}},"description":"Installations metadata successfully retrieved"},"400":{"content":{"application/json":{"example":{"code":0,"message":"Invalid request arguments."}}},"description":"Invalid or missing parameters"},"401":{"content":{"application/json":{"example":{"code":0,"message":"Invalid token."}}},"description":"Unauthorized (invalid token)"},"500":{"content":{"application/json":{"example":{"code":0,"message":"Internal Server Error."}}},"description":"Internal server error"}},"summary":"Retrieve installations metadata from the database","tags":["Installations"]}},"/api/installations/register":{"post":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/RegisterInstallation"}}],"responses":{"201":{"description":"Installation successfully registered","schema":{"properties":{"code":{"example":1,"type":"integer"},"message":{"example":"ok","type":"string"}},"type":"object"}},"400":{"description":"Invalid request parameters","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"'country' param must be one of the following: ['portugal', 'spain', 'france']","type":"string"}},"type":"object"}},"401":{"description":"Unauthorized (missing or invalid token)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Invalid token.","type":"string"}},"type":"object"}},"500":{"description":"Internal server error (DB or NWP grid failure)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Unable to register. Failed to insert installation metadata.","type":"string"}},"type":"object"}}},"summary":"Register a new installation","tags":["Installations"]}},"/api/installations/status":{"patch":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/PatchInstallationStatus"}}],"responses":{"201":{"description":"Installation status updated successfully","schema":{"properties":{"code":{"example":1,"type":"integer"},"message":{"example":"ok","type":"string"}},"type":"object"}},"400":{"description":"Invalid request body (schema validation failed)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"'installation_code' is a required property","type":"string"}},"type":"object"}},"401":{"description":"Unauthorized (missing or invalid token)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Invalid token.","type":"string"}},"type":"object"}},"500":{"description":"Internal server error (failed DB update)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Failed to register installation.","type":"string"}},"type":"object"}}},"summary":"Update the active status of an installation","tags":["Installations"]}},"/api/user/list":{"get":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"}],"responses":{"200":{"content":{"application/json":{"example":[{"email":"admin@example.com","last_login":"2025-09-18 09:42:11","registered_at":"2025-01-10 14:22:31","role":"admin","username":"admin"},{"email":"jane@example.com","last_login":"2025-09-17 17:20:45","registered_at":"2025-03-04 08:15:00","role":"user","username":"jane"}]}},"description":"List of users successfully retrieved"},"401":{"content":{"application/json":{"example":{"code":0,"message":"Invalid token."}}},"description":"Unauthorized (invalid or missing admin token)"},"500":{"content":{"application/json":{"example":{"code":0,"message":"Internal Server Error."}}},"description":"Internal server error"}},"security":[{"bearerAuth":[]}],"summary":"Retrieve the list of registered users","tags":["Users"]}},"/api/user/login":{"post":{"parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/Login"}}],"responses":{"200":{"description":"Successful login, JWT token generated","schema":{"properties":{"code":{"example":1,"type":"integer"},"duration":{"description":"Token duration in seconds","example":3600,"type":"integer"},"token":{"description":"Bearer token to be used in subsequent requests","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","type":"string"}},"type":"object"}},"400":{"description":"Invalid request body (schema validation failed)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"'password' is a required property","type":"string"}},"type":"object"}},"401":{"description":"Unauthorized (invalid username or password)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Unauthorized: Invalid username/password.","type":"string"}},"type":"object"}},"500":{"description":"Internal server error","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Internal Server Error.","type":"string"}},"type":"object"}}},"summary":"User login and token generation","tags":["Authentication"]}},"/api/user/password-reset":{"patch":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/ResetPassword"}}],"responses":{"201":{"description":"Password reset successful","schema":{"properties":{"code":{"example":1,"type":"integer"},"message":{"example":"Successful password reset. Please login again with the new credentials.","type":"string"}},"type":"object"}},"400":{"description":"Invalid request body or authorization mismatch","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Invalid authorization token.","type":"string"}},"type":"object"}},"401":{"description":"Unauthorized (invalid token or wrong username/password)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Unauthorized: Invalid username/password.","type":"string"}},"type":"object"}},"500":{"description":"Internal server error while updating password","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Internal Server Error.","type":"string"}},"type":"object"}}},"summary":"Reset a user's password","tags":["Users"]}},"/api/user/permissions":{"put":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/UpdateUserPermission"}}],"responses":{"201":{"description":"User permissions successfully updated","schema":{"properties":{"code":{"example":1,"type":"integer"},"message":{"example":"ok","type":"string"}},"type":"object"}},"400":{"description":"Invalid request body or invalid permission level","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"That's not a valid permission level. Valid levels: ['none','basic','intermediate','advanced','admin']","type":"string"}},"type":"object"}},"401":{"description":"Unauthorized (invalid token or username not found)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Invalid username.","type":"string"}},"type":"object"}},"500":{"description":"Internal server error while updating permissions","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Failed to update permissions for user 'jane'.","type":"string"}},"type":"object"}}},"summary":"Update a user's permissions","tags":["Users"]}},"/api/user/register":{"post":{"parameters":[{"description":"Bearer JWT token with `admin` privileges. Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`\n","in":"header","name":"Authorization","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/RegisterUser"}}],"responses":{"201":{"description":"User successfully registered","schema":{"properties":{"code":{"example":1,"type":"integer"},"message":{"example":"ok","type":"string"},"token":{"description":"JWT token issued for the new user","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","type":"string"}},"type":"object"}},"400":{"description":"Missing required fields or invalid request body","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Missing password.","type":"string"}},"type":"object"}},"401":{"description":"Unauthorized (invalid or missing admin token)","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Invalid token.","type":"string"}},"type":"object"}},"500":{"description":"Internal server error while registering user","schema":{"properties":{"code":{"example":0,"type":"integer"},"message":{"example":"Failed to register new user.","type":"string"}},"type":"object"}}},"summary":"Register a new user","tags":["Users"]}}},"swagger":"2.0"}