API Reference

Complete reference for the Ampra REST API. All endpoints are served under https://api.ampra.solar/api/.

---

Base URL

Environment	Base URL
Production	https://api.ampra.solar/api
Local Development	http://localhost:5001/api

---

Authentication

Ampra uses cookie-based session authentication. After a successful login, the server sets an HttpOnly, Secure, SameSite=Lax cookie with a 7-day sliding expiration window.

Session Lifecycle

POST /api/auth/login   →  Sets authentication cookie
     ↓
  (Authenticated requests carry cookie automatically)
     ↓
POST /api/auth/logout  →  Clears authentication cookie

Endpoints marked with require a valid session cookie. Endpoints marked with may require specific roles.

---

Authorization Model

Role	Level	Description
User	Standard	Default role — access to own resources
Admin	Elevated	User management, system administration
Overseer	Supreme	Full system access, debug operations

Policies

Policy	Roles	Applied To
Omni	User, Admin, Overseer	Data controllers (metrics, data)
Admin,Overseer	Admin, Overseer	Admin controller

---

Content Types

Direction	Content-Type
Request Body	application/json
Response Body	application/json
File Upload	multipart/form-data
CSV Export	text/csv
Excel Export	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

---

Error Handling

All errors follow a consistent response structure. The GlobalExceptionMiddleware maps exceptions to appropriate HTTP status codes.

Error Response Format

{
  "message": "Human-readable error description"
}

Validation Error Format

{
  "errors": {
    "Email": ["The Email field is required."],
    "Password": ["Password must be at least 8 characters."]
  }
}

Status Code Reference

Code	Meaning	When Returned
200	OK	Successful GET, PUT, POST operations
201	Created	Resource creation (includes Location header)
204	No Content	Successful DELETE operations
400	Bad Request	Validation failure, invalid parameters
401	Unauthorized	Missing or expired session
403	Forbidden	Insufficient role permissions
404	Not Found	Resource does not exist or not owned
500	Internal Server Error	Unhandled server exception
503	Service Unavailable	External dependency down (weather API, ML service)

---

Rate Limiting & Constraints

Constraint	Limit
Email verification code resend	Rate-limited per account
Webhook payload size	64 KB maximum
Image upload size	5 MB maximum
Batch metrics request	50 sources maximum
History query limit	1,000 records maximum
CSV/Excel export range	33 days maximum
Daily summary range	400 days maximum
Aggregated data range	90 days maximum
Pagination page size	1–100 (clamped)

---

CORS Configuration

Setting	Value
Allowed Origins	Configured via CORS_ALLOWED_ORIGINS
Allowed Methods	Any
Allowed Headers	Any
Credentials	Enabled

---

Endpoint Index

Controller	Route Prefix	Auth	Endpoints
Authentication	/api/auth	Mixed	6
Administration	/api/admin	Admin+	4
Sun Sources	/api/sunsources	User	8
Power Groups	/api/powergroups	User	5
Telemetry Data	/api/sunsourcedata	Omni	11
Metrics	/api/sunsourcemetrics	Omni	6
Predictions	/api/predictions	User	5
ROI & Pricing	/api/roi	User	5
Weather	/api/weather	User	2
Sharing	/api/sharing	Mixed	8
Export	/api/export	User	2
Upload	/api/upload	User	2
Settings	/api/settings	User	2
Webhooks	/api/webhook	Public	1
MQTT Auth	/api/internal/mqtt	Internal	2