Sun Sources

Management of solar energy sources — the core resource in Ampra representing a physical inverter or installation.

Base Route: /api/sunsources
Authorization: Required (all endpoints)

List Sun Sources

Returns all Sun Sources owned by the authenticated user, optionally filtered by Power Group.

GET /api/sunsources?powerGroupId=550e8400-e29b-41d4-a716-446655440000

Query Parameters

Parameter	Type	Required	Description
`powerGroupId`	`Guid`	No	Filter by Power Group

Response `200 OK`

[
  {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Roof Array Alpha",
    "description": "Main rooftop installation",
    "iconUrl": "https://minio.ampra.solar/uploads/user123/image.png",
    "powerGroupId": "550e8400-e29b-41d4-a716-446655440000",
    "powerGroupName": "Home Installation",
    "connectionType": "MQTT",
    "latitude": 45.4642,
    "longitude": 9.1900,
    "isActive": true,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-06-20T14:22:00Z",
    "installedCapacityWatts": 5000.0,
    "currency": "EUR",
    "systemCost": 12500.00,
    "maintenanceCostPerYear": 250.00,
    "installationDate": "2024-06-01T00:00:00Z",
    "connectionDetails": null
  }
]

note

Connection details are never included in list responses. Use the detail endpoint with includeConnectionDetails=true to retrieve sensitive credentials.

Get Sun Source

Returns a single Sun Source with optional connection details.

GET /api/sunsources/{id}?includeConnectionDetails=true

Path Parameters

Parameter	Type	Description
`id`	`Guid`	Sun Source ID

Query Parameters

Parameter	Type	Default	Description
`includeConnectionDetails`	`bool`	`false`	Include MQTT/Webhook credentials

Response `200 OK` (with connection details)

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Roof Array Alpha",
  "description": "Main rooftop installation",
  "iconUrl": "https://minio.ampra.solar/uploads/user123/image.png",
  "powerGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "powerGroupName": "Home Installation",
  "connectionType": "MQTT",
  "latitude": 45.4642,
  "longitude": 9.1900,
  "isActive": true,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-06-20T14:22:00Z",
  "installedCapacityWatts": 5000.0,
  "currency": "EUR",
  "systemCost": 12500.00,
  "maintenanceCostPerYear": 250.00,
  "installationDate": "2024-06-01T00:00:00Z",
  "connectionDetails": {
    "mqttBrokerHost": "emqx.ampra.solar",
    "mqttBrokerPort": 8883,
    "mqttClientId": "sunsource_7c9e6679",
    "mqttApiKey": "ak_xxxxxxxxxxxxxxxxxxxxxxxx",
    "mqttTopic": "sunsource/7c9e6679-7425-40de-944b-e07fc1f90ae7/data",
    "webhookUrl": null,
    "webhookSecret": null
  }
}

Create Sun Source

Creates a new Sun Source. Automatically generates MQTT credentials or webhook configuration based on the connection type.

POST /api/sunsources

Request Body

{
  "name": "Roof Array Alpha",
  "description": "Main rooftop installation",
  "iconUrl": "https://minio.ampra.solar/uploads/user123/image.png",
  "powerGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "connectionType": "MQTT",
  "latitude": 45.4642,
  "longitude": 9.1900,
  "installedCapacityWatts": 5000.0,
  "currency": "EUR",
  "initialKwhPrice": 0.25,
  "systemCost": 12500.00,
  "maintenanceCostPerYear": 250.00,
  "installationDate": "2024-06-01T00:00:00Z"
}

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Display name
`description`	`string`	No	`null`	Description
`iconUrl`	`string`	No	`null`	Icon URL (uploaded via `/api/upload/image`)
`powerGroupId`	`Guid`	No	`null`	Assign to Power Group
`connectionType`	`string`	Yes	—	`"MQTT"` or `"Webhook"`
`latitude`	`double`	No	`null`	GPS latitude (required for weather/predictions)
`longitude`	`double`	No	`null`	GPS longitude (required for weather/predictions)
`webhookSecret`	`string`	No	Auto-generated	Custom webhook secret (Webhook type only)
`installedCapacityWatts`	`double`	No	`null`	Panel capacity in watts
`currency`	`string`	No	`"EUR"`	Currency code for ROI calculations
`initialKwhPrice`	`double`	No	`null`	Initial energy price (creates first KwhPriceHistory entry)
`systemCost`	`decimal`	No	`null`	Total system cost for ROI
`maintenanceCostPerYear`	`decimal`	No	`null`	Annual maintenance cost
`installationDate`	`DateTime`	No	`null`	Installation date

Auto-Generated Credentials

For MQTT type:

mqttTopic: sunsource/{sourceId}/data
mqttApiKey: Cryptographically random 32-byte key (base64url)

For Webhook type:

webhookUrl: https://api.ampra.solar/api/webhook/sunsource/{sourceId}
webhookSecret: Provided value or auto-generated 32-byte key

Response `201 Created`

Returns the created SunSourceDto with Location header.

Update Sun Source

Updates an existing Sun Source's configuration.

PUT /api/sunsources/{id}

Request Body

{
  "name": "Updated Array Name",
  "description": "Updated description",
  "powerGroupId": "550e8400-e29b-41d4-a716-446655440000",
  "isActive": true,
  "latitude": 45.4642,
  "longitude": 9.1900,
  "regenerateMqttApiKey": false,
  "installedCapacityWatts": 6000.0,
  "currency": "EUR",
  "systemCost": 15000.00,
  "maintenanceCostPerYear": 300.00,
  "installationDate": "2024-06-01T00:00:00Z"
}

Field	Type	Description
`name`	`string`	Display name
`description`	`string?`	Description
`iconUrl`	`string?`	Icon URL
`powerGroupId`	`Guid?`	Power Group assignment (set `null` to unassign)
`isActive`	`bool?`	Activate/deactivate
`latitude`	`double?`	GPS latitude
`longitude`	`double?`	GPS longitude
`regenerateMqttApiKey`	`bool`	Set `true` to rotate MQTT API key
`installedCapacityWatts`	`double?`	Panel capacity
`currency`	`string?`	Currency code
`systemCost`	`decimal?`	Total system cost
`maintenanceCostPerYear`	`decimal?`	Annual maintenance
`installationDate`	`DateTime?`	Installation date

Response `200 OK`

Returns the updated SunSourceDto.

Delete Sun Source

Permanently removes a Sun Source and all associated data.

DELETE /api/sunsources/{id}

Response `204 No Content`

Cascade Deletion

Resource	Storage	Behavior
Sun Source record	PostgreSQL	Deleted
All telemetry data	MongoDB	All documents for this source removed
Sharing configuration	PostgreSQL	Cascade deleted
KWh price history	PostgreSQL	Cascade deleted
Weather data	PostgreSQL	Cascade deleted

Get Webhook URL

Generates the full webhook URL for a Sun Source.

GET /api/sunsources/{id}/webhook-url

Response `200 OK`

{
  "webhookUrl": "https://api.ampra.solar/api/webhook/sunsource/7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Rotate Webhook Secret

Generates a new webhook secret, invalidating the previous one.

POST /api/sunsources/{id}/rotate-secret

Response `200 OK`

{
  "webhookSecret": "wh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Regenerate MQTT Key

Generates a new MQTT API key. The previous key is immediately invalidated.

POST /api/sunsources/{id}/regenerate-mqtt-key

Response `200 OK`

{
  "mqttApiKey": "ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

warning

Rotating credentials immediately disconnects any devices using the old credentials. Ensure all connected devices are updated promptly.

Response Schema: `SunSourceDto`

interface SunSourceDto {
  id: string;                        // UUID
  name: string;
  description: string | null;
  iconUrl: string | null;
  powerGroupId: string | null;       // UUID
  powerGroupName: string | null;
  connectionType: "MQTT" | "Webhook";
  latitude: number | null;
  longitude: number | null;
  isActive: boolean;
  createdAt: string;                 // ISO 8601
  updatedAt: string;                 // ISO 8601
  installedCapacityWatts: number | null;
  currency: string;                  // Default: "EUR"
  systemCost: number | null;
  maintenanceCostPerYear: number | null;
  installationDate: string | null;   // ISO 8601
  connectionDetails: SunSourceConnectionDetailsDto | null;
}

interface SunSourceConnectionDetailsDto {
  mqttBrokerHost: string | null;
  mqttBrokerPort: number | null;
  mqttClientId: string | null;
  mqttApiKey: string | null;
  mqttTopic: string | null;
  webhookUrl: string | null;
  webhookSecret: string | null;
}

List Sun Sources​

Query Parameters​

Response 200 OK​

Get Sun Source​

Path Parameters​

Query Parameters​

Response 200 OK (with connection details)​

Create Sun Source​

Request Body​

Auto-Generated Credentials​

Response 201 Created​

Update Sun Source​

Request Body​

Response 200 OK​

Delete Sun Source​

Response 204 No Content​

Cascade Deletion​

Get Webhook URL​

Response 200 OK​

Rotate Webhook Secret​

Response 200 OK​

Regenerate MQTT Key​

Response 200 OK​

Response Schema: SunSourceDto​

List Sun Sources

Query Parameters

Response `200 OK`

Get Sun Source

Path Parameters

Query Parameters

Response `200 OK` (with connection details)

Create Sun Source

Request Body

Auto-Generated Credentials

Response `201 Created`

Update Sun Source

Request Body

Response `200 OK`

Delete Sun Source

Response `204 No Content`

Cascade Deletion

Get Webhook URL

Response `200 OK`

Rotate Webhook Secret

Response `200 OK`

Regenerate MQTT Key

Response `200 OK`

Response Schema: `SunSourceDto`